030-3621-A 




MPW 3.2 


Release Notes 


Erratum 

Due to an oversight, an erroneous comment symbol was used in lines 20 through 24 of the 
source file: 

{MPW}PExamples:TESampleGlue.a 

The character “#” was incorrectly written where the character should have been written. 
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MPW 3.2 

Release Notes 


This release note summarizes the differences between MPW 3.2 and MPW 3.0, the last 
version for which a reference manual exists. Details beyond those given in this note are to 
be found in separate release notes entided MPW 3.2 Shell, MPW 3.2 Object Pascal, MPW 
3.2 C, MPW 3.2 Assembler, MPW 3.2 Libraries & Interfaces, MPW 3.2 “411” Help, 
MPW 3.2 Run-Time Architecture, MPW 3.2 SIOW, and MPW 3.2 Tools & Scripts. 
Three of the above: “411” Help, Run-Time Architecture, and SIOW describe completely 
new features. 


Principal Changes 


Shell 

■ Projector has a number of enhancements. 

■ The Editor provides split windows. 

■ A marker browser has been provided. 

■ There are additional commands for the faccess function. 

■ The save command, when scripted, saves the resource fork of a file if any resource has 
changed. 

■ MPW can now be run under A/UX. 

■ New System 7.0 error codes have been added to the file SysErrs.err. 


C 

■ A variety of new object code optimizations have been implemented. 

■ There are new compiler options to control optimization level. 
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■ Support is provided for the MacApp debugger and code profilers (generating a preamble 
and postamble for functions). 

■ A new pragma is provided for passing parameters to functions via registers. 

■ A new pragma is provided to force the generation of MC68020 code. 

■ A new pragma is provided to prevent the multiple inclusion of header files. 

■ There is a new option for invoking the “32-bit everything” run-time architecture. 

■ A new pragma is provided to prevent dead code stripping by the linker. 

■ An option is provided for machines having the MC68020 and up that allows stand-alone 
code segments greater than 32K. 


Object Pascal 

■ Further object code optimizations, including an optional two-pass code generation phase 
which allocates unused scratch registers for local data. 

■ An option to control optimization level. 

■ An option for invoking the “32-bit everything” run-time architecture. 

■ A new syntax for declaring forward and external objects 

■ Enhancements to the Object Pascal declaration handling to support MacApp. 

■ Support for USES clauses in the implementation section of a unit. 

■ Support for external C functions with arbitrary numbers of arguments,. 

■ The ability to omit static links for nested procedures that don’t need them. 

■ Increase in the number of nested include files, the maximum number of nested compile¬ 
time conditionals, and in the number of long identifiers. 


ASM 

■ New optimizations. 

■ Longer identifiers to support C++ name mangling. 

■ MC68040 support. 

■ A new parameter and syntax for module directives. 

■ “32-Bit Everything” support. 
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Improved SADE support. 

A new macro function: &SYSINMOD. 


Tools/Scripts 

■ The Link, Lib, DumpCode, and DumpObj tools support an improved form of data 
initialization. 

■ The Search tool has some new options and its performance has been improved. 

■ The DumpCode and DumpObj tools provide support for 68040 development. 

■ The Object Pascal compiler, C compiler, ASM, and Link support “32-bit 
Everything,” which is a capability for simultaneously exceeding the 32K limit on code 
segment sizes, the size of the jump table, and the size of the application globals space. 

■ Link has an option which causes the automatic generation of “branch islands.” This 
permits code segments to be larger than 32K. 

■ A new StreamEdit tool provides for scriptable editing of text streams similar to that 
provided by Unix’s Sed tool. 

■ Make includes extensions to the default rule mechanism and new built-in variables. 

■ Choose has new options to prompt for “secure” passwords with a dialog box. 

■ ProcNames and PasRef now process “$” compiler directives such as conditional 
compilation directives. ProcNames has been modified to generate MPW Shell com¬ 
mands to mark all of the procedures and functions in a file. 

■ FileDiv has been enhanced to handle non-text files. 

■ Compare has been modified to support a larger number of lines in the files being 
compared. 


Libraries/Interfaces 

■ CRuntime.o and Runtime.o have been merged into a single Runtime.o. 

■ The libraries have been resegmented to move more modules out of the “main” segment. 

■ The C libraries conform to the ANSI specification. 

■ The Pascal libraries include standard C string functions which work on Pascal strings. 

■ There is a new library supporting a simple input/output window application known as 
SIOW. 
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■ The SANE libraries have performance enhancements. 

■ New Interfaces support several SANE enhancements and support System 7.0. 

■ CIncludes has been changed to eliminate glue code in calling certain Macintosh Toolbox 
routines. 


Miscellaneous 

■ A new facility, “411” Help, provides rapid on-line access to development information 
while using MPW. Because of this size of the database, “411” Help will be distributed 
on CD only. 


Important Note for Users of Virus Detectors 

A number of virus detectors, e.g.. Vaccine™ and SAM™ think that the MPW Linker is a 
virus because the Linker routinely creates and modifies ‘CODE’ resources. The behavior 
may range from the Linker appearing to hang to multiple appearances of a window request¬ 
ing permission to proceed. This problem can possibly be corrected by changing the pro¬ 
tection level of the virus detector. If all else fails, the detector can be temporarily disabled. 


Important Note for Users of The Debugger V2 & MacNosy 

Attempts to use the above products with MPW 3.2 will result in a bus error. The following 
change to the MPW Shell will remove the problem: 

Using ResEdit, change the bytes at offsets $46B4 and $4722 in CODE resource ID 5 from 
$67 to $60. 
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Reporting Bugs 


Please report any bugs you find to Apple. Use the application “Outside Bug Reporter,” 
found on the MPW Installation Disk. After completing the bug report, send it 


via AppleLink to: APPLE.BUGS 


via US Mail to: 

Apple Computer, Inc. 

Bug Report Center 

20525 Mariani Ave. MS 27-AN 

Cupertino, CA 95014 

♦ Apple Partners who are in critical need of a work-around solution should contact 
MacDTS 


via AppleLink to: MACDTS 


via US Mail to: 

Apple Computer, Inc. 
Developer Technical Support 
20525 Mariani Ave. MS 75-3T 
Cupertino, CA 95014 


System Requirements 

MPW 3.2 requires a hard disk and at least 2 Mb of RAM. Actually, the MPW Shell’s 
MultiFinder partition size comes set at 2048K. In order to compile and link large programs 
with symbolic information, it may be necessary to increase MPW Shell’s memory partition 
size. SADE requires MultiFinder and at least 2.5 Mb of RAM. MPW 3.2 requires System 
6.0 and Finder 6.1 (or later). 
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MPW 3.2 Shell 

Release Notes 


MPW 3.2 is the first release since MPW 3.0 that goes significantly beyond bug fixes. The 
new MPW Shell incorporates safety features for Projector, split windows and miscella¬ 
neous improvements for the editor, an enhanced set of window commands, enhanced tool 
support via f access , and a simple marker browser. A scripted save command saves the 
resource fork of a file when any resource has changed. The “Mark” menu has been en¬ 
hanced with the item “Alphabetic”; this toggles the list of marks between alphabetic order 
and the order of their appearance in the file The Shell is now truly 32-bit clean and runs 
also in the AUX 2.0 environment. 


A Important About testing tools: Memory management in the Shell has changed. The 
Shell no longer checks the heap before and after tools run; this is a con¬ 
sequence of following the rules for being “32-bit clean.” 

One way to see if tools are working correctly is to use MacsBug’s HC 
command. For example, you can have this command executed every 
time a tool starts by using the following from inside MacsBug: 

BR STARTTOOL HC; G' 

This, however, has the disadvantage of causing the MacsBug window to 
flash momentarily on the screen, a 


A Important After GetFileName brings up the Standard File dialog when MPW is 
running in the background (under MultiFinder), switching MPW to the 
foreground will cause the computer to hang. The cause of this has not 
been determined, but it may be a System 7 problem, a 


♦ Note: The default shell partition is now 2048K bytes (0x200000) and the default stack 
size is is 64K bytes (0x10000). Also, most work to be done under MPW 3.2 requires 
at least 256K more memory than it did under previous releases. 
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/access Commands 


The MPW Shell now contains code for several new f access commands. The #def ine 
statements for the command names and the typedef for MarkElement are in 
(CIncludes} FCntl.h. The interface is: 

int faccess(char *filename, unsigned int command, long *arg); 

These commands require that the file be open. 

The new commands are: 

F_GSCROLLINFO Sets *arg to the value 1 if scrolling is locked; to the value 0 if it 


F_SSCROLLINFO 

is unlocked. 

Locks scrolling if the value of *arg is non-zero; unlocks 
scrolling if it is zero. 

F.SMARKER 

Sets a file marker according to the specification in the structure 
*arg. This structure is defined by: 

F_SSAVEONCLOSE 

typedef struct MarkElement { 

int start; //start position of mark 
int end; //end position of mark*/ 
unsigned char charCount; // no. of chars. 

// in mark name 

char name[l]; // first char, of mark name 
} MarkElement; 

Note: The user must allocate sufficient contiguous space to 
hold an instance of MarkElement followed by a zero-terminated 
mark name. The necessary data items followed by the string 
must then be copied into this space. 

Sets the status of “save on close.” If *arg is 0 (SaveNormal), 
the normal prompt to the user is given. If *arg is 1 
(SaveNever), the window is not saved. If *arg is 2 
(SaveAlways), the window is saved. 

F_GSAVEONCLOSE 

Sets *arg to 0,1, or 2, respectively, depending on whether the 
“save on close” status is SaveNormal, SaveNever, or 
SaveAlways. 
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(For calling instructions when using assembly language or Pascal, see Chapter 12 of the 
MPW 3.0 Reference Manual.) 


Save 


The Save command (scripted) will now force a save of the resource fork of a file if the 
format (font/tabs), scroll bar, window position, etc. has been modified, even if the text of 
the file has not been modified. Note that the “Save” menu item will continue to operate as 
before, including the fact that it will be disabled unless the text of the file has been modi¬ 
fied. 


Editor 


Markers 

A new item appears in the initial section of the “Mark” menu. It is a toggle labelled 
“Alphabetical.” When a check mark appears next to this label, the marks shown in the pop¬ 
up menu will be in alphabetical order. Otherwise, the order is the sequence in which the 
marked lines appear in the window. 

If the first character supplied for a marker name is a hyphen, the remaining characters are 
ignored, and the marker menu will show a menu separation line (a gray, one-pixel line). 
This line will appear in the menu exactly where a normal marker name, if supplied, would 
have appeared. The line will not show when the “Alphabetical” mode is selected from the 
Mark menu. 
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Keyboard Commands 


The set of editing actions that are available from the keyboard has been extended. The set 
is shown in the matrix below. 

The actions “move word to right/left” and “extend selection word to right/left” require pre¬ 
cise definition. A word is defined to be a contiguous group of characters chosen from the 
set defined by the shell variable wordset, the default value of which is a-zA-z_o-9. The 
point to which the insertion point moves, or the selection is extended, is from the current 
position to the far edge of the nearest word in the direction of motion. The end of the line 
provides an exception. If there are characters not in wordset after the last word found (in 
the direction of motion) on the line, then the cursor motion or selection extension stops at 
the furthest of these characters before proceeding to the next line (again, in the direction of 
motion). For example, given the following lines: 

Now is the time for— 
to come to the aid 

consecutive applications of option will move the cursor from the right-hand edge of 
“time” to the right-hand edge of “for” to just beyond “--” and then to the right-hand edge of 
“to”. 
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delete del * <- -> T ^ 


shift 

option 

shift 

option 

cmd 


cmd 

shift 


cmd 

option 


cmd 

shift 

option 


deletes 
character to 
left 

deletes 
character to 
right 

moves 

character 
to left 

moves 

character to 
right 

move one 
lineup 

moves one 

line down 

deletes 

deletes 

extends 

extends 

extends 

extends 

character to 

character to 

selection 

selection 

selection 

selection 

left 

right 

character 

character to 

one line up 

one line 



to left 

right 


down 

deletes 

deletes 

moves 

moves 

moves one 

moves one 

word to 

word to 

word to 

word to 

lineup 

line down 

left 

right 

left 

right 



beep 

beep 

extends 

extends 

extends 

extends 



selection 

selection 

selection 

selection 



word to 

word to 

one line up 

one line 



left 

right 


down 

deletes to 

deletes to 

moves to 

moves to 

moves one 

moves one 

end of file 

end of file 

beginning 

end of line 

page up 

page down 



of line 




beep 

beep 

extends 

extends 

extends 

extends 



selection to 

selection to 

selection 

selection 



beginning 

end of line 

one page 

one page 



of line 


up 

down 

deletes to 

deletes to 

moves to 

moves to 

moves to 

moves to 

end of file 

end of file 

beginning 

end of line 

beginning 

end of file 



of line 


of file 


beep 

beep 

extends 

extends 

extends 

extends 



selection to 

selection to 

selection to 

selection to 



beginning 

end of line 

beginning 

end of file 



of line 


of file 



* del is available on extended keyboard only 
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Windows 


A new feature of the MPW Shell Editor is the capability to split windows. Each pane has 
both vertical and horizontal scroll bars. As specified in the Human Interface Guide: The 
Apple Desktop Interface , the user can create new panes by dragging the black rectangle 
(split bar ) at the top/left of the scroll bar; the panes can be resized by dragging the slide box 
that is adjacent to the split bar or deleted by moving the slide box as far as possible in the 
direction of its origin. The split bar creates a new pane; the slide box resizes (possibly 
down to zero) an existing pane. Each pane is independently controllable (scroll and resize), 
which increases flexibility in viewing a text file. 

Extensions have been made to the set of commands that deal with windows. 

♦ Note: The “Do It” button has been moved to the top of the window. 


Editor Window 

Status Box ("Do It") 



HP:MPUJ:EHamples:CEHamples:EditCdeu.r i 


resource 'DHL* (-4064) { 

< /* array DITLarray: 1 elements */ 

/* [1] */ 

<60, 110, 76, 280), 

EditText < 
enabled, 

/* [21 */ 

<85, 110, 101, 280), 

EditText < 

enabled, "" 

/* [31 */ 

<15, 110, 50, 280), 

StaticText < 

^ disabled, M Apple Macintosh Developer 


); 


> 


resource ’FREF’ (-4064, purgeable) < 
* cdev *, 0, "" 

) / 

resource *nrcf <-4064, purgeable) < 

ED 


Macintosh Developer Technical SupportJJ 
EditText Sample Control Panel Device 
EditCdev 

EditCdev.make - Make Source 

Copyright $ 1988 Apple Computer, lnc.| 
All righ ts reserved. 

_ Versions: 1.1 _7/88 

p<PI I.: ", ' 1 “""i' ' '|0 : 


O 


resource *ICN«' <-4064, purgeable) < 

< /* array: 2 elements */ 

/* m */ 

$-00 00 00 00 00 00 3F EO 00 00 4 

$“00 01 83 10 00 02 01 90 00 04 

$-00 04 01 90 00 04 03 90 00 04 0 

$-00 08 02 90 00 08 02 90 00 10 0 

$-03 CO 18 90 04 00 3F 10 OF FF C 

$-08 00 00 10 08 00 00 10 08 00 F 

$-08 00 00 10 08 00 00 10 08 00 0 

$"04 00 00 20 04 00 00 20 04 00 



Ijl&iMiljilll 


Mil 


; 

nil 

BBS 


Split Bar 


I 


si 


Slide Box 
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Window Commands 


The Windows command has a new option, -o, that causes the pathnames to be written as 
a set of Open commands. 

Syntax 

Windows # list windows 

Windows [-q] [-o] 

-q # don't quote window names with 

# special characters 

-o # write out the "Open..." commands 

The -o option causes the list to consist of a series of Open commands, one per line, con¬ 
taining the “-r” option for the case of read-only files. 

♦ Note: The Suspend script has been modified to make use of windows -o. 

The RotateWindows command has a new option that reverses the direction of rotation. 

Syntax 

RotateWindows # send active (frontmost) window to back 

RotateWindows [-r] 

-r # reverse rotation; 

# bring bottom window to front 

The Format command has anew attribute pair associated with the -a option. The option- 
attribute combinations are: 

-a L # lock auto scrolling 

-a 1 # unlock auto scrolling 

There are four new commands: ShowSelection, SaveOnClose, AddPane, and 
DeletePane. 

Syntax 

ShowSelection 

ShowSelection [-t 
-t 
-b 
-c 

-n lines 

MPW 3.2 Shell 
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# place the selection in the desired window 

# position 

I -b | -c | -n lines I -1 line] [window] 

# pin selection to top of window 

# pin selection to bottom of window 

# pin selection in center of window 

# move selection to "lines" from top 
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-1 line 


# move the line numbered "line" to the 

# top of the window 


This command scrolls the window, setting the selection to the desired position. If a win¬ 
dow is not named, the default is the target window. 

♦ If the selection is in the window at the time of execution of the above command, the 
window will not scroll. (See Known Outstanding Bugs.) 


Syntax 


SaveOnClose 
SaveOnClose [-a | -d 
-a 
-d 
-n 


# set window saving preference 
-n] [window] 

# always save window when closing 

# default (ask Yes/No/Cancel) 

# never save window when closing 


Note: The -n option does not deactivate the Save menu item; the user may always save 
explicitly. 

This command selects an automatic behavior: save (-a), do not save (-n), or ask whether to 
save when closing a window (-d). If a window is not named, the default is the target win¬ 
dow. 

The SaveOnClose option is not permanent; its effect will not persist beyond the closing of 
the window. Non-default “save on close” status is shown by one of the following icons in 
the upper right-hand comer of the window: 




The left-hand one denotes “never save on close”; the right hand one denotes “always save 
on close.” 

If no option is given for this command, the behavior is to return a complete command line 
of the form: SaveOnClose <option> <f ull window pathname>, thus showing the 
SaveOnClose status of the named window. 
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♦ The next two commands, AddPane and DeletePane, are illustrated by an example 
that immediately follows the formal syntax presentations. 


Syntax 


AddPane 

AddPane [-p paneSpec] 
-p paneSpec 
-y ySplit 

-x xSplit 


# split the window into panes 
[-y ySplit | -x xSplit] [window] 

# choose a pane to split 

# put a horizontal scroll bar at ySplit pixels 

# from the top edge of the pane 

# put a vertical scroll bar at xSplit pixels 

# from the left edge of the pane 


This command selects a pane of a window and then splits the pane as specified. paneSpec 
identifies a pane by a path that starts at the largest subdivision and works toward the small¬ 
est. paneSpec is a catenation of strings of the form “c/m” or “r/m” where the “c” and “r” 
stand respectively for row and column and “ m ” is an appropriate ordinal (see examples 
below). If neither the -y nor the -x options are given, a set of AddPane commands, which 
would have produced the window as shown, is sent to standard output. If the -p option is 
omitted, the pane that is split is the active pane, i.e., the pane last written into. If a window 
is not named, the default is the target window. 

Syntax 

DeletePane # delete panes from the window 

DeletePane [-p paneSpec I -a] [window] 

-p paneSpec # choose a pane to delete 

-a # reset the window to have a single pane 

This command selects a pane of a window and deletes it by removal of a scroll bar. 
paneSpec has the same definition and use as is given above in the description of AddPane. 
If the pane to be deleted is part of a row, the scroll bar on its right is deleted unless the pane 
is the rightmost pane of the row, in which case the scroll bar on the left is deleted. If the 
pane to be deleted is part of a column, the scroll bar at its bottom is deleted unless it is the 

lowest pane of the column, in which case the scroll bar at its top is deleted. If neither op¬ 

tion -p or -a are given, the pane that is deleted is the active pane, i.e., the pane last written 
into. If a window is not named, the default is the target window. 
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Example 


■ A multi-paned window. Each pane is labelled with its panespec. 
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The command AddPane hd : mpw : panetest displays the following commands, which 

would produce the above tiling when starting with an unpaned window: 

addpane -p •' -x 159 hd:mpw:panetest 

addpane -p cl -y 219 hd:mpw:panetest 

addpane -p c2 -y 163 hd:mpw:panetest 

addpane -p c2r2 -y 135 hd:mpw:panetest 

addpane -p c2r2 -x 110 hd:mpw:panetest 

addpane -p c2r2c2 -x 113 hd:mpw:panetest 

addpane -p c2r2c3 -x 136 hd:mpw:panetest 

addpane -p c2r3 -x 161 hd:mpw:panetest 

addpane -p c2r3c2 -x 120 hd:mpw:panetest 

♦ Note: addpane -p • 1 -x 159 <window> is equivalent to 
addpane -v 159 <window>. 


Browser 

The Browser presents users with a standard file/directory list, similar to that of the “open” 
dialog box. If a file has been selected, a pane on the right shows all markers belonging to 
that file. Upon selecting and double-clicking a marker, the Shell will open the appropriate 
file and find the selected marker. If a marker is known, but the file containing it is un¬ 
known, a field for entering a string allows the user to search for a file that contains that 
string as a marker or a part thereof. 

The Browser window is opened by executing the command Browser or choosing Browse 
from the Mark menu. 
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■ Browser Window 



Marker List 


File List 


Field for Find 


T 


Frontmost Window 
Buttons 


File List 

This pane shows all of the text files within the specified directory. Clicking on a filename 
causes the Marker List to display all of the markers within that file. Double-clicking on a 
filename opens the file. All aspects of file and directory selection work the same way as for 
the dialog box that appears when opening a file from an application, e.g. typing the initial 
letters of a file or directory name, use of the cursor control keys and of the latter in con¬ 
junction with the command key. 
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Marker List 

This pane shows all of the markers within the selected file. Double-clicking on a marker 
opens the selected file to the selected marker. 

♦ See Also: Mark command and the tools CMarker and ProcNames. 


Field for Find 

The user can type into this pane a string for comparison to all markers in all files in the cur¬ 
rent directory. Pressing Return or Enter causes the Browser to search for the marker that 
contains this string (even as a proper substring) and to select it. If the marker appears in 
more than one file, the first such appearance in the file list is selected. If the Open after 
find box has been checked, the file with the desired marker is automatically opened with 
the marked item selected. 


Find Mark Button 

This button will open the currently selected file to the currently selected marker if the cur¬ 
rent pane is the marker list (see Pane Selection below). Otherwise, if the current pane is the 
find field, it will begin searching for the text in the find field. Once one occurrence of a 
mark is found, this button changes to Find Next until the mark is deselected. 


Frontmost Window Buttons 

These radio buttons determine whether the window, when opened, is to be the frontmost 
window (Open as Active), or the window immediately behind the Browser window (Open 
as Target). 
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Pane Selection 

The currently selected pane is indicated as follows: for File List and Marker List by a 
heavy border, for Field for Find by the blinking of the cursor. The default selection is 
Field for Find. The selection can be advanced, rotating among the three panes, by 
pressing Tab. When either the File List or Marker List pane is selected, typing the initial 
letter or letters of a name will select an item in the same manner as is done in the conven¬ 
tional dialogue windows for opening files. 


Projector 


♦ Note: A tutorial on Projector can be found as Appendix G of these Release Notes. 


A number of improvements have been made to Projector. This includes correction of some 
deficiencies in the Commando interfaces, provision for checkout from and checkin to an 
NFS (UNIX Network File System) site, and the set of changes that are detailed below. 


Cancel Checkout 

To reduce the probability of an erroneous cancellation of a checkout, an alert box stating the 
identity of the owner of a checked out revision will appear when any user who is not the 
owner starts to cancel the checkout. When a checkout is cancelled, Projector will change 
the file from modifiable to read-only provided the file is to be found in the current checkout 
directory. If the file is not found there, an alert box with a warning message will appear. 
Cancel Checkout is now logged; instances of cancellation can be examined by use of the 
command Pro jectinfo with the option -log. 


AppleShare Use 

Projector now supports multiple simultaneous reads from a Projector database. Thus, sev¬ 
eral users can simultaneously check files out without incurring delay. If, however, any 
user is writing to the database, other users are temporarily locked out. Conversely, a user 
wishing to write to the database is temporarily locked out if any other users are reading or 
writing. 
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Time-outs 

If a user is temporarily locked out under the circumstances described above, a “retrying...” 
dialog box is displayed. The user has the option to cancel. Formerly, cancellation took 
place automatically after 80 retries. 


ModifyReadOnly 

More than one file name can now be written in the command line of a single 
ModifyReadOnly command. 


NameRevisions, DeleteNames 

The default for NameRevisions and DeleteNames has been changed from private to public. 
This required the introduction of a new option: -private. The old option, -public, is 
being kept so as not to invalidate old scripts. The behavior then is: 

1. -public will work as before. 

2. The new option, -private, must be used to define private names. 

3. Not specifying an option gives the default value: -public. 

4. Using the -b option (both) with NameRevisions will work as follows: when listing 
names (no files specified), both public and private names will be listed; when creating a 
name, -b will default to public. 


OrphanFiles 

OrphanFiles no longer changes the modification date of the file. 


Verify 

This feature was added to Projector after a number of experiences with loss of data from 
rotating magnetic storage. It is activated for Checkin and Checkout by marking a check 
box labelled “Verify” in the respective window, or by using the option -verify in the 
respective command line. The effects are as follows: 
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For Checkout: The file is checked out out normally and checked out out a second time as a 
temporary file. The data forks of the two files are then compared. If they 
are equal, the temporary file is deleted. If they are unequal, the temporary 
file is saved, an error message is printed to stdErr, and a status of 2 is 
returned. 

For Checkin: The file is checked in, and then checked out as a temporary file. The data 
forks of the temporary file and the copy that had been checked in are com¬ 
pared. If they are equal, the temporary file is deleted. If they are unequal, 
the temporary file is saved, an error message is printed to StdErr, and a 
status of 2 is returned. 

If the -p option is combined with the -verify option, a message will be emitted saying 
that the file has been verified 


Warning Messages (-newer and -update) 


When executing a Checkout command with either of the options -newer or -update, 
various circumstances may prevent the checkout of one or more files. Warning messages 
are now issued for each such file, indicating the reason for the failure. The message for¬ 
mats are: 

NOT checked out: Your file <filename> is a modified read-only file. 

NOT checked out: Your file <filename> is a modifiable file on a branch. 

NOT checked out: Your file <filename> is on a branch. 

NOT checked out: Your file <filename> belongs to another project. 

NOT checked out: Your file <filename> has no ckid resource. 

WARNING: Your file <filename> is modifiable but the checkout was 
cancelled. 

WARNING: Your file <filename> is not part of the project. 


The first of the above warnings is issued only if the modified read-only file is not the latest 
revision. 


The last of these is possibly not self-explanatory. It indicates that a DeieteRevisions 
command completely removed all revisions of die file from the Projector database. Then, a 
file bearing the same name as the file in question was checked in. 

In the event that the Checkout window is used with the Select Newer button (with or with¬ 
out the Option key), and one of the above circumstances occurs, a dialog box will be dis¬ 
played with the message: 

“WARNING: Some files have not been selected because they are not read-only, not part of 
the project or have some other problem. Use the 'checkout -newer' command for more 
detailed information.” 
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Known Outstanding Bugs 


■ Editor performance suffers when files have an excessive number of marks (of the order 
of 100 to 200, depending on the speed of the cpu). 

■ (System 7) File aliases are not fully supported. They are currently usable only with the 
open command. 

■ When using showseiection, if the selection is in the window at the time of execution 
the window will not scroll. 

■ Under System 7, tools that attempt to bring up the Standard File dialog in the back¬ 
ground will bring up an empty window and totally freeze the computer so that only a 
manual restart is possible. 


Bug Fixes 


General 

■ The MPW Shell no longer hangs as a consequence of executing the Beep command 
while running in the background. 

■ The Shell no longer limits the stack of a tool to 200K. 

■ When using the Apple Extended Keyboard and Multifinder, the Cut, Copy, and Paste 
keys (F1-F3) now always update the clipboard when switching between applications. 

■ The Files command now correctly calculates the sizes of non-boot volumes when 
using the -i, -x, and -l options. 

■ The Files command formerly did not in all cases print out fill file names when the -f 
and -n options were used in conjunction with -x or -l. This bug has been fixed. 
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Projector 


■ Output from the NameRevisions command can now be interrupted by use of 
Command-Period. 

■ Formerly, Canceicheckout, when applied to a branch, would under certain circum¬ 
stances cancel the wrong revision. This no longer occurs. 

■ A bug, which could cause database corruption under near-full-disk situations, has been 
fixed. 
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MPW 3.2 Tools/Scripts 
Release Notes 


Tools 

Several new tools appear in this release. 

■ StreamEdit is a scriptable text editor similar to the editor sed that is found in UNIX®. 

■ CMarker generates markers at function definitions in C++/ANSIC source files. 

■ Get, developed for “411” Help, is available for general use. See the MPW 3.2 “411” 
Help Release Notes for information about “411”. 

A number of improvements have been made to existing tools. 

■ Choose has two new options for prompting for passwords. 

■ Compare has had its line number limitation raised from 9999 to 65535. 

■ DumpObj has a slightly changed -m option. The argument can now be either a mod¬ 
ule name or an entry point name. If it is the latter, the meaning is to dump the module 
that contains the named entry point. Any number of instances this option may now ap¬ 
pear in a command line. 

■ FileDiv has been enhanced to give the user the option of considering its input file as a 
stream of bytes. 

■ The option -sort has been added to GetListltem. 

■ The performance of Search has improved as the result of search algorithm and buffer¬ 
ing changes. Four new options have been added. 

■ Link has a new data initialization routine to reduce the size of the compressed data 
image in the link output Appropriate changes have been made to DumpCode for con¬ 
formity with this change in Link. Options have been added to Link, one to accommo¬ 
date a new run-time architecture (“32-Bit Everything”), the other to cause automatic gen¬ 
eration of branch islands. 

■ Link and Lib, upon failure, will set that date of the output file to numeric zero 
(1 January 1904). 
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■ Make has several new features. The default rule mechanism has been extended so that 
it may identify optional additional dependencies in addition to the single dependency 
permitted by the current mechanism. A default build rule has been added for C++. A 
new predefined variable, {Deps} stands for all of the dependencies of a target A new 
predefined target, $OutOf Date can be used to force other targets to be rebuilt A new 
option, -y, provides a limited form of the verbose option output. 

■ ProcNames has been enhanced to generate MPW Shell “mark” commands that set 
markers on all procedures and functions in an Object Pascal file. It has also been en¬ 
hanced to process conditional compilation directives. 

■ PasRef has been enhanced to process conditional compilation directives. The maxi¬ 
mum number of symbols it can handle has been raised from 5000 to 6000. 

■ ResEqual now looks at resource attribute flags. 

A A bug has been reported in DumpCode. Information will not be dumped correctly 
from a module that has been compiled and linked as “model far” and that 
contains any A5-relocatable information. 

A partial work-around for this is to use the “-ri” option, which inhibits 
the dumping of relocation information. This will, at least, permit correct 
dumping of code, a 


Backup 

A bug that has now been fixed prevented the creation of inner folders when the when the 
-t option was used to limit recursive processing (-r) to files of a specific type. 


Choose 

The following options, that prompt for “secure” passwords with a dialog box, have been 
added: 

-askpw #prompt for the server password. Illegal in conjunction 
with -pw or -guest. 

-askvp # prompt for the volume password. Illegal in conjunction 
with -vp or -guest. 
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CMarker 

CMarker reads the specified C++ / ANSI C source file(s), syntax checks them and gener¬ 
ates appropriate "Open" and "Mark" MPW commands, which, when executed, will mark 
the source file(s) at each function definition with the marker name being the name of the 
function. Its purpose is to aid in the marking of source files for use with the MPW "marker 
browser" capability. CMarker contains a full ANSI C preprocessor and provides options 
to mark include files, generate source listings (with or without showing macro expan¬ 
sions), run the preprocessor only, flag anachronisms, and syntax check C++ / ANSI C 
with or without Apple extensions. 

(See Appendix B for the CMarker manual.) 


Commando 

The following bug has been fixed: conditionals in Commando resources were not always 
evaluated correctly when a set of dependencies was not a simple tree but a directed acyclic 
graph. An illustration of this would be two entries, B and C, both dependent on A, with D 
dependent on the expression (B or C). 


Compare 

The maximum number of lines in the files being compared has been raised. The limitation 
section of the manual should be amended to read: “The maximum number of lines in the 
text files read by Compare should be less than 65535.” 


DumpCode 

DumpCode now stops disassembling at the end of the resource (rather than skidding to a 
halt a few bytes beyond). It recognizes and dumps the new data initialization format used 
by Link. 


DumpObj 

The -mods option prints a summary of the contents of an object file, including the name, 
size, scope and segment of each module and entry point. This means you can find out 
what's in an object file without dumping the entire file. 
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More information is being dumped (flags are printed in English, logical addresses are 
disassembled, and so forth). 


Type data fixups are now printed correctly. 


FileDiv 

FileDiv now allows an input file to be viewed as containing an arbitrary byte stream in its 
data fork. 

(See Appendix F for changes to the FileDiv manual.) 


Get 

Get is a tool for retrieving information from a data base indexed by a BTree. It will not 
only retrieve information, but will also create and update the index file when required. 

Get is heavily oriented to the needs of the menu-driven “411”. Direct calls to it could be for 
the purpose of retrieving information from the “411” database in a different manner from 
that provided in “411”, or for accessing a database that is totally independent of “411”. 

Information on how to construct database files can be found in the section entitled ‘Adding 
your own help to “411”’ in the MPW 3.2 “411” Help Release Notes. 

(See Appendix C for the Get manual.) 


GetListltem 

The option -sort has been added. Use of this option will cause the list in the dialogue box 
to appear in sorted order. 


Lib 

Lib now supports the -mf option to allocate MultiFinder temporary memory when the 
MPW Shell heap runs low. See the documentation (and warnings) about -mf in the Link 
manual page. 
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Link 


Data Initialization 

A new data initialization compression routine was added to Link to provide a more compact 
representation of the data image within link output. The routine originated from the need 
for better compression of C++ VTables. An associated _DATAINIT module exists within 
the 3.2 alpha Runtime.o library to expand the data image into the proper below-A5 world. 
The new routine may reduce the size of the %A5Init segment by up to 33%. Link will re¬ 
vert to using the original data initialization compression routine when older libraries are 
linked. 


New Options 

Two new options deal with removal of various 32K size limitations. For technical expla¬ 
nation, see the MPW 3.2 Run-Time Architecture Release Notes. 

Branch Islands 

A new option has been defined to cause the automatic generation of branch islands to 
remove the 32K limit on segment size. The syntax is: 

-br on # generate branch islands where needed 

-br off # do not generate branch islands (default) 

♦ The -br on option should not be used simultaneously with the -model far option. 


A Important Because of an outstanding bug, attempting to use the -br on option 
simultaneously with the -sn option may cause a crash, a 


"32-Bit Everything” 

A new option has been defined to accommodate the “32-Bit Everything” method of remov¬ 
ing the 32K limit on segment size, jump table size, and the size of the global data area. 
They are: 

-model near # the default 

-model far 

If any of the code being linked was compiled with a “far” option, it is necessary to link 
with the option -model far. 
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New Keywords (-opt option) 

The -opt option accepts two additional keywords: 

-opt names SelectorProcs are modules generated by the linker to be 

used at run-time for Object Pascal method dispatching. 

This keyword causes MacsBug symbols to be appended to 
SelectorProc modules so that the selector names are visible 
in MacsBug disassemblies. The MacsBug symbols take up 
space in the application, both on disk and in memory (e.g. 
9K or more for a medium MacApp application). 

-opt info Write method table optimization information to diagnostics. 

This information was previously written to diagnostics 
using the ‘-p’ option and was moved to the ‘Info’ subarg 
to reduce the size of the linker diagnostics when optimiz¬ 
ing. 


Object Pascal Optimization 

Jump table entries for monomorphic methods are now being snipped. This is an inten¬ 
tional step of the optimizer, although it may present problems when trying to call an Object 
Pascal method from a C++ program. To work around the dispatching problem, use the 
NoBypass subargument to -opt to bypass monomorphic method optimization when opti¬ 
mizing. 

Symbolics 

The format of Sym files has changed to support Object Pascal and FORTRAN. Use the 
1.3 SADE with the MPW 3.2 Linker (you can't mix old and new Sym files or SADEs — 
please delete your existing Sym files). Contact DTS for the details of the Sym file and 
OMF changes. 

Miscellaneous 

The linker now returns an error when the size of the jump table has reached the maximum 
number of jump table entries. 
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Previously, when the -ad option was used, the linker would align every data module in¬ 
cluding the main data module, if one existed. This was unacceptable since MPW Pascal 
makes A5-relative references to data in the main data module assuming that it is located 
immediately below A5. The -ad option will now correctly align data while leaving the main 
data module immediately below A5. 

There is now no limit to the size of global data that is compressed into the %A5Init data 
initialization segment. There was previously a limit of 32K. 

When linking using the -mf option, if memory conditions continue to be tight, the flush 
command may be used to recover additional space from the shell’s cache. 

Various cosmetic changes have been made to the -l and -map output. 


Make 

The new version of Make for MPW 3.2 includes several new features. 

The default rule mechanism has been extended so it may identify optional additional depen¬ 
dencies in addition to the single dependency permitted by the current mechanism. This new 
capability has immediate applications to MacApp builds. 

A default build rule has been added for C++ files, which are recognized by the suffix . cp. 

Make supports a new predefined variable, {Deps}, which stands for all of the dependen¬ 
cies of a target. 

Make also supports a new predefined target, $OutOfDate, which can be used to force other 
targets to be rebuilt. 

A new option, -y, has been provided. This option tells why build rules were emitted, but 
in a less verbose form than the existing -v option. Namely, it does not emit messages 
about up-to-date targets. 

Default Rules Extension 

Default rules formerly had the following form: 

.extensionl / .extension2 

<build rules> 

This syntax has been extended as follows: 

.extensionl f .extension2 [other dependencies ...] 

<build rules> 
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The other dependencies can be more file extensions and/or fixed file names. These depen¬ 
dencies are considered secondary or optional dependencies as is explained below. 

The first extension on the right hand side of a default rule is treated as the primary 
dependency (or trigger dependency), that is, the file name created with this extension 
(i.e., “{depdir} {default}.extension!”) must be valid in order for the default rule to be trig¬ 
gered or applied. To be valid a file name must either appear in the makefile or exist in the 
file system (or lead to a valid file name by further recursive applications of default rules). 
The existence or non-existence of files specified by secondary dependencies will have no 
effect on whether the rule is triggered, thus default rules are triggered just as they were be¬ 
fore. 

Secondary dependencies are optional; that is, none are required, and the indicated file 
(or files) need not be valid for the default rule to be applied. Secondary dependencies are 
only processed when a default rule is triggered by its primary dependency. When the sec¬ 
ondary dependency is a fixed file name, a dependency will be added if the secondary de¬ 
pendency refers to a valid file name. Similarly, when the secondary dependency is a file 
extension (e.g., “.extension3”) a dependency will be added if the file name implied by this 
extension (i.e., “{depdir} {default}.extension3”) refers to a valid file name. If a file name 
specified by a secondary dependency is not valid then no dependency is added and the de¬ 
fault rule is processed as usual. 

Applications. This extension will be useful for MacApp, where typically a source file 
consists of a file with the interface and an include with the implementation. Now the de¬ 
pendency of the object file on both source files can be stated in a single rule, such as the 
one below: 

.p.o f .p .p.incl 

<normal Pascal build rule> 

“Deps” Variable 


The predefined “{Deps}” variable may be used in a target’s build rules and represents all of 
the (first-level) dependencies of the target (as opposed to {NewerDeps} which represents 
only those dependencies which are newer than the target). 

The {Deps} variable can be used to write a default rule for links or application builds where 
all of the dependency files will be linked together, such as: 


f .o 


• O 


{Link} {LinkOptions} {Deps} -o {TargDir}{Default} 
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“$OutOfDate” Target 


The predefined “$OutOfDate” target is an artificial target which is always out of date and 
never needs to be rebuilt One can force a target to be rebuilt by making it depend on 
$OutOfDate. 

For example: 


ForceRebuild = # default variable definition (NOP) 

foo f (ForceRebuild) 

<build foo> 

If Make is invoked normally the target “foo” will not be rebuilt; however, it will be rebuilt 
if invoked with the following command line: 

Make -d ForceRebuild=$OutOfDate 

This command line has the effect of overriding the vacuous definition of “ForceRebuild” in 
the makefile while giving foo a dependency on $OutOfDate which forces it to be rebuilt 


PasMat 

The following bug, pertaining to the j formatting directive, has been fixed: 
j=<width>[±]/<coll>[sd]/<col2>c 

did not handle the case where <coi2> could be 1. 


PasRef 

Options have been added to permit processing of conditional compilation directives. The 
limitation on the number of symbols has been raised from 5000 to 6000. 

(See Appendix E for changes to the PasRef manual.) 
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ProcNames 

ProcNames can be directed to generate MPW Shell “mark” commands that place markers 
on all procedures and functions in an Object Pascal file. 

Options have been added to permit processing of conditional compilation directives. 

(See Appendix D for changes to the ProcNames manual.) 


ResEqual 

ResEqual now compares resource attribute flags for equality and reports any differences 
found. 


Rez 

Avoid splitting expressions with #if or #elif commands, for example: 

type 'TEST' { 
int; 

} ; 

♦define big 5 
resource 'TEST' (128) { 

10 // this will not work because the expression is split 

#if big 

* 45 

tendif 
} ; 


♦ Attention is directed to the material in the MPW 3.0 Reference Manual with respect to 
the arguments of the -c and -t options. These arguments are Rez expressions. If a 
special character within the expression requires that it be enclosed in single quotes, it is 
necessary to surround the quoted expression with double quotes. E.g. -c " ' §§§' ". 
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Search 

The following options have been added: 

-b # break File/Line output text into two lines 

-nf # write error message if pattern not found 

-ns # return 0 when pattern not found 

-sf # stop the search at the first successful match 

Improvements in the search algorithm and in the buffering have greatly enhanced the per¬ 
formance. 


Sort 

A bug in Sort prevented the sorting of field expressions that include column offsets or 
counts. For example, a call of Sort with the option 
-f 1.3+4 

would fail to do any actual sorting. This bug has been fixed. 


StreamEdit 

StreamEdit is an non-interactive text editor similar in function to the Unix® tool sed. 
Providing scriptable text matching and editing operations, it is useful for making repetitive 
changes to files, for extracting information from text files, or as a filter. 

StreamEdit takes a script and a set of input files (or standard input, if no input files are 
specified) and applies each statement in the script to each line of input, writing the output to 
standard output or the specified output file. 

(See Appendix A for the StreamEdit manual.) 
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Scripts 


CompareFiles 


The CompareFiles command now has two more options for specifying screen size: 

-TwoPage # screen size for Apple Two-Page Monochrome Monitor 

-Portrait # screen size for Apple Macintosh Portrait Display 


CreateMake 

Enhancements to CreateMake are: 

■ A check box for providing symbolic information to the SADE debugger. This will ap¬ 
ply the -sym on option to the generated command lines for compilation and linking. 
The check box is dimmed for desk accessories, because the method for building them 
produced by CreateMake is note compatible with SADE. 

■ Radio buttons for the options -mc68020, -mc68881, and -elems881. 

■ Provision for the building of objects of a new type: SIOW application. This type is de¬ 
scribed in the MPW 3.2 SIOW Release Note. 

Other changes are: 

■ CreateMake now creates correct Makefiles for building cdevs and most stand-alone code 
resources. Desk accessories remain a problem since there are several different methods 
for building the header at the start of a desk accessory. CreateMake will produce a cor¬ 
rect makefile for one of the methods used in the Memory DA examples found in the 
CExamples and PExamples folders. This build technique is the same as that found in 
MPW 3.0, but is not compatible with SADE. For information see the Instructions file in 
the CExamples or PExamples folder. In conclusion, if you are building a desk acces¬ 
sory, you probably shouldn’t be using CreateMake to produce the makefile. 

■ CreateMake recognizes that the functions of the libraries CRuntime.o and CInterfaces.o 
have now been absorbed into Runtime.o and Interfaces.o; it therefore no longer puts 
CRuntime.o and CInterfaces.o into the library list for li nkin g, 
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■ The compilation and linking command lines generated by CreateMake no longer have the 
-w option; warnings will be issued. The only exception is that the link command line 
for a tool has the -d option, thus suppressing the duplicate definition warnings that 
would normally be issued because of the use of Stubs.o. 

■ If any source file is written in Object Pascal or C++ (filenames with the extensions . p or 
. cp), the line #" { Libraries } n ob jLib. o will appear in the link. 
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MPW 3.2 Run-Time Architecture 
Enhancements 
Release Notes 


Introduction 


The original execution environment of the Macintosh was designed for a machine with 
128K of RAM and a 68000 CPU. In order to cope with a memory this small, dynamic 
relocation of almost everything was a necessity. It had to be possible to move segments of 
code, to purge them when not needed, and to reload them elsewhere than their original 
location when needed again. The initial architecture restricted the size of each of the fol¬ 
lowing to 32K: code segments, the global data area, and the jump table (described below). 
This execution environment is considered to be an extremely efficient one within the stated 
constraints. 

Throughout the history of MPW, various enhancements to MPW tools have been made 
with the purpose removing one or another of these 32K restrictions. The following sec¬ 
tions of these Release Notes show how to apply the available alternatives: 

■ Direct compiler generation of A5-relative data references with offsets exceeding 32K. 

■ Direct function calls within a code segment greater than 32K by use of the 68020 PC- 
relative branch with 32-bit displacement (C compiler, 68020 only). 

■ Making function calls within a code segment greater than 32K by using “branch 
islands.” 

■ A Link option providing for extension of the jump table to more than 32K by utilizing 
part of the application globals space. 

■ The “32-Bit Everything” solution, which extends application globals, code segments, 
and the jump table to more than 32K each by performing address “fixups” at load time. 

The remaining sections of these Notes describe the technology of the “32-Bit Everything” 
solution in detail, present a number of essential caveats, and describe a new run-time li¬ 
brary and interface that is directed to applications (and debuggers) which might be explicitly 
concerned with the “32-Bit Everything” Segment Loader patches. 
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Breaking the 32K limit 


More than 32K of global data (all 680x0 machines) 

The compiler option -m, available for both Pascal and C, causes generation of code se¬ 
quences that yield A5-relative references (execution-time A5 value) with 32-bit offsets. 

A typical sequence is: 

MOVEA.L A5,A0 

ADDA.L <32-bit offset>,A0 

WHATEVER (AO) 

Without the -m option, the code would be: 

WHATEVER <16-bitoffset>(AS) 

In either case, the offsets are supplied by the Linker. 

Disadvantages: Code is larger and slower 


Code segments greater than 32K (C compiler, 68020 and above) 

The C compiler option -bigseg causes function calls within the same segment to be en¬ 
coded with the 68020 bsr. l instruction, which is a PC-relative instruction with a 32-bit 
offset. 

Disadvantage: Not available to 68000 machines. 

Advantage: Useful for large single-segment code, e.g. XCMDs. 


Branch islands—a universal technique for large code segments 

A simple, effective technique for implementing PC-relative code-to-code references within 
a segment that exceeds 32K in size is to split the segment into two independently compiled 
modules each of which is under 32K, and to include as a sandwich between these two por¬ 
tions a small assembly-language module (a "branch island") that transmits calls between 
the two. In other words, the original call is modified to be a jsr to the branch island and 
the latter contains a bra to the desired target. For usage information, see the Link section 
of the MPW 3.2 Tools/Scripts Release Notes. 


MPW 3.2 Run-Time Architecture 2 Copyright Apple Computer, Inc. 

Enhancements 1990-1991. All rights reserved. 

Release Notes 







Large jump tables 


A Linker option, -wrap, makes it possible for jump tables to be larger than 32K by utiliz¬ 
ing unused space in the global data area for jump table entries when the jump table space 
has been exhausted. This is particularly useful for MacApp programs. Because they make 
little demand on global data space, this option significantly increases the size of the applica¬ 
tions that can be generated with MacApp. 

Disadvantage: Of limited utility. At best, can double the jump table size. Not applicable if 
the global data area is filled with data. 


“32-Bit Everything” 

This is a complete and almost transparent method of removing all three limitations: on code 
segment size, jump table size, and the size of the global data area. The cost to the applica¬ 
tions developer is a slight increase in code size and a slight increase in the time to load a 
code segment The method is activated by using certain options when compiling and link¬ 
ing. The compiler options permit choice, on a compilation unit basis, of full 32-bit offsets 
for global data (-Model f arData), full 32-bit offsets for code references (-Model 
f arCode), or both (-Model far). Linking of modules compiled with any such combina¬ 
tion is supported; the only requirement is that if any 32-bit option has been used with any 
of the compilation units, the linking must be done with the option -Model far. The 
increase in code size has three causes: each reference occupies two bytes of additional stor¬ 
age, and the Linker inserts into the executable file relocation information that is used when 
loading and about IK of code that patches the Segment Loader. The increase in load time 
is caused by dynamic relocation of the 32-bit references during loading. Global data refer¬ 
ences and code references via the jump table are relocated by adding the load-time value of 
A5. Intra-segment code references are relocated by adding the load address of the segment. 

Compiler and Linker options 

The options are: 

Compiler options (Object Pascal and C): 

-Model near # the default 

-Model far 

which respectively choose the stated model for both code and data, 

-Model nearData # again, the default 
-Model farData 

which chooses a model for data only, and 
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-Model nearCode # default 
-Model farCode 


which chooses a model for code only. 


Linker options: 

-model near # the default 


-model far 

If any code being linked was compiled (or assembled) with any “far” option, it is an error 
to attempt linking without specifying the option -model far. 

Assembly language options and techniques 

In assembly language, the use of a 32-bit reference for the target address of an instruction 
must be explicitly demanded by use of the absolute long address syntax (xxx). l, where 
“xxx” is a relocatable expression. Two further requirements are that the relevant operand 
symbol be imported, and that the option -model far be used for the assembly. The re¬ 
quirement that the symbol be imported means that the defining occurrence of the symbol 
must be in a different module from the instances of use as 32-bit references. Since the ab¬ 
solute long address syntax by definition specifies absolute operands, the use of this form 
with a relocatable symbol is an error unless the option -model far is invoked. The ab¬ 
sence of the option -model far (the default) can be explicitly shown by use of the option 
-model near. 

Global data references, references to code in the same segment, and references to code in a 
different segment all cause the assembler to produce similar records, records that tell the 
Linker that a 32-bit patch will be needed. The Linker observes whether the references are 
to code or data, and in the former case, whether the reference is within the same segment or 
not. 

The following example illustrates the technique: 


MAIN 


IMPORT 

IMPORT 

IMPORT 

JSR 


STUFF 
THERE 
ELSEWHERE 
(THERE).L 
(ELSEWHERE).L 
(STUFF).L,DO 


Symbols from other 
modules must be 
imported. 

Symbols are written 
using (xxx).L syntax. 


JSR 


ADD.W 

ENDMAIN 


THERE 


PROC 

EXPORT 

NOP 

ENDPROC 


THERE 


Note that THERE 
is in the MAIN 
segment. 
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Note that ELSEWHERE 
is in a different 
segment. 

ELSEWHERE NOP 

ENDPROC 

PROC 

DATA 

EXPORT STUFF 

STUFF DS 1 

ENDPROC 
END 


SEG 1 SGI 1 

PROC 

EXPORT ELSEWHERE 


Known problems 

■ The 32-Bit Everything mechanism patches the _LoadSeg trap. Therefore, if user code 
calls _LoadSeg directly or patches _LoadSeg, unpredictable behavior may occur. 

■ The objLib.o library does not support 32-Bit Everything. Because of this, code using 
Pascal Objects will not work with 32-Bit Everything. This does not apply to MacApp, 
whose library does support 32-Bit Everything. 

■ It is in general not correct to combine Object Pascal objects compiled respectively with 
differing choices of the near and far options. The Linker will consider this circumstance 
to be an error. 

■ The user should be aware that using the “far” option results in the creation of code 
which is not “pure.” Because the code is modified when loaded (or reloaded), check 
sums become invalid and attempts to share code are likely to fail. 


Technical details of “32-Bit Everything” 


Recapitulation of 16-bit technology 

In order to provide for relocatability of code segments, all code-to-code references within a 
segment are written as PC-relative, so that the code need have no knowledge of where it is 
loaded. This nominally restricts the size of segments to 32K because the PC-relative in¬ 
structions on a 68000 use a 16-bit offset. Current ways of removing this restriction are not 
fully satisfactory, as a direct 32-bit branch is available only on the 68020 or higher. 
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References from code to global data appear as A5-relative addresses with negative offsets. 
The present method of dealing with more than 32K of global data is to generate 68000 in¬ 
struction sequences that implement 32-bit A5-relative references. (The equivalent 68020 
addressing mode is slow, and using it would introduce an undesirable processor restric¬ 
tion.) 

Code references from one segment to another are performed as indirect references via the 
dynamically maintained jump table. Details of the jump table format are given in the 
Segment Loader chapter of Inside Macintosh (Vol. II, Ch. 2). The jump table is loaded at a 
small positive offset from A5, and references to it are encoded as A5-relative addresses 
with positive offsets. Each procedure or function which is an entry point to its segment is 
therefore represented in the code as an A5-relative address, this address being created by 
the Linker. The A5-relative addressing mode suggests that the jump table be limited to 
32K. Other architectural considerations in fact prevent extension of this limit. 

In order to help the reader understand the description of the new addressing mec hanisms , a 
short summary of the current jump table mechanism follows. For more details, see the 
above-named chapter of Inside Macintosh . The jump table entries for the procedures of 
any given segment are contiguous. They appear in two alternate formats, depending on 
whether or not the segment has been loaded. The “unloaded” format contains the all the 
information the segment loader needs to construct an absolute jump instruction to the pro¬ 
cedure. The information is: the segment number and the offset of the procedure from the 
start of its segment. A subroutine jump to the “unloaded” jump table entry results in a call 
of the Segment Loader to load the segment and to modify all jump table entries to the 
“loaded” format. In this latter format, the jump table entry holds, in the same eight bytes, 
the segment number and the previously-mentioned absolute jump instruction. When the 
segment is purged, the segment loader reverses the process, and returns that segment’s 
jump table entries to the “unloaded” format. Each segment starts with a header, containing 
information that the Segment Loader needs in order to perform the switch between “loaded” 
and “unloaded” formats. This information is the offset of the first entry for that segment 
from the start of the jump table and the number of jump table entries belonging to the seg¬ 
ment. 

In summary, the system was designed with a nominal restriction to 16-bit addresses for 
several types of references, and the various methods of partial removal of this restriction 
are not considered adequate. What is wanted is a consistent, unified, backwards- 
compatible, and efficient way of removing the restriction. 
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The “32-Bit Everything” solution 


The tricky part of removing the restriction to 16-bit addressing is to do it in such a way that 
the changes are almost transparent. If we refer to code with 16-bit addressing as code ac¬ 
cording to the “near” model, and code with 32-bit addressing as the “far” model, then one 
ground rule is that the Linker should happily accept a mixture of segments compiled with 
different models. Since the code making an intersegment reference cannot “know” the 
model of the addressee, the code must make the call via the jump table in a model- 
independent manner. This, of course, also requires that there be no change in the size of a 
jump table entry. 

There are three types of references which must be considered: code to data, intra-segment 
code to code, and inter-segment code to code. Each of these is described in detail below. 
The basic methodology is the same for each: instead of having compilers generate PC- 
relative and A5-relative instructions, both having 16-bit offsets, have compilers instead 
generate instructions with 32-bit addresses, and relocate these addresses at load time by the 
segment load address or by the contents of A5, as is appropriate. Obviously the Segment 
Loader must change. The way in which this change has been implemented will be de¬ 
scribed later. 

Code-to-data 

If compilation and linking are performed with any option that specifies the “far” model for 
data, then all instructions which reference global data are generated with 32-bit absolute ad¬ 
dresses. These addresses are the offsets of the data items relative to A5. The location of 
each such instruction making such a reference is stored in compressed form in an area 
called “A5 relocation information.” The modified Segment Loader, using this information 
and the value of A5 at load time, relocates each such instruction during loading by adding 
the value of A5 to the 32-bit address field of the instruction. This provides a more efficient 
method than hitherto available for referencing a global data area that exceeds 32K. 


Code-to-code (intra-segment) 

If compilation and linking are performed with any option that specifies the “far” model for 
code, then all instructions which make intra-segment code references are generated with 32- 
bit absolute addresses. These addresses are the byte offsets from the beginning of the 
segment to the referenced points. The location of each instruction making such a reference 
will be stored in compressed form in an area called “segment relocation information.” The 
modified Segment Loader relocates each such instruction at load time by adding the load 
address of the segment to the 32-bit address field of the instruction. This permits a seg¬ 
ment to be over 32K in length. 


MPW 3.2 Run-Time Architecture 7 Copyright Apple Computer, Inc. 

Enhancements 1990-1991. All rights reserved. 

Release Notes 









Code-to-code (inter-segment) 


Compilation and linking with the “far” model causes the simultaneous removal of two pre¬ 
vious restrictions: the limitation of the jump table and segment size to 32K bytes each. 
Because segments compiled under the “near” module may be linked with other segments 
that were compiled as “far,” the jump table entries for “near” segments precede those for 
“far” ones. Thus, there still may be a portion of the jump table as large as 32K containing 
“near” entries before the start of the “far” entries. A segment compiled/linked as “far” may 
exceed 32K; therefore four bytes are required in a jump table entry to describe the offset of 
a function from the beginning of its segment This requires a reorganization of the jump 
table from the “classic” {Inside Macintosh) structure. Because of the requirement simulta¬ 
neously to support the “near” and “far” models, all jump table entries must be of the same 
size, and preferably of the same format The new format follows: 


■ Jump table entry 


Unloaded Loaded 


2-byte 

segment number 

2-byte 

segment number 

2-byte 

LoadSeg 

6-byte 

JMP $xxxxxxxx 

4-byte 

segment offset 




Only the entries for unloaded segments differ from the “classic” jump table entries docu¬ 
mented in Inside Macintosh. By omitting the instruction that stacks the segment number 
(letting the Segment Loader fetch the segment number from the entry itself), two bytes are 
saved, making possible the recording of a 4-byte offset. 

References to “far” jump table entries are handled in a similar way to global data references. 
JSR instructions with absolute addresses are generated, the addresses of these instructions 
are recorded as “A5 relocation information,” and the (modified) Segment Loader adds the 
value of A5 to the address fields of the JSR instructions at load time. 
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Because MPW rides on top of an existing system, it was decided to create the modified 
Segment Loader by patching the one supplied by the system. The scenario is that, if the 
“far” model is requested, the Linker puts the code needed to do this patching into the appli¬ 
cation itself. The first entry in the jump table is a “classic” entry, understood by the stan¬ 
dard Segment Loader, which points to the patch code. Execution of this code causes the 
desired modifications of the Loader. The remainder of the jump table is in the new format, 
this part being separated from the first entry by a “flag” entry of which the first word is 
reserved and must be zero, the second is a version field (nominally $FFFF), and the re¬ 
maining two words are zero. The third jump table entry addresses the main entry point of 
the application. The following illustration shows the start of the jump table: 


MPW 3.2 Run-Time Architecture 9 Copyright Apple Computer, Inc. 

Enhancements 1990-1991. All rights reserved. 

Release Notes 




■ Jump table structure 


$0 

$0004 (segment offset) 

$2 

move.w #1, -(SP) 


(put seg number on stack) 

$6 

LoadSeg (Seg Loader trap) 

$8 

$0000 (reserved) 

$A 

$FFFF (version) 

$C 

$0000 (reserved) 

$10 

$0002 (seg number) 


LoadSeg 


segment offset 




“Classic” format entry 


“Flag” entry 


First new format entry 


A Important The format of the jump table for "32-bit Everything" is subject to change. 

Developers are cautioned against assuming any dependency on the format 
reported here, a 
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The standard Segment Loader loads 'CODE' resource 0 (jump table) and 'CODE' resource 
1 in the usual manner. (The first entry in the jump table is a “classic” entry, understood by 
the unmodified Segment Loader.) The contents of code(l), when executed, patches the 
Segment Loader so that it can load and unload 32-bit segments. Code(l) also patches 
chain, Launch, and ExitToSheii so that, when executed, they unpatch the Segment 
Loader and then execute normally. Finally, Code(l) calls the third jump table entry. 
Because the third entry has not yet been loaded, loading is now performed by the modified 
Segment Loader, which, after verifying that the “flag” entry in the jump table is correct 
with respect to the version field in the segment header, updates all PC-relative and A5- 
relative references while loading the code. If a segment has been moved, or A5 has 
changed since the segment was loaded, then the jump table entries for the segment revert to 
the “unloaded” format, and the modified segment loader will add to the addresses in the 
code that need updating the respective changes in the load address and in the A5 contents. 


32-bit segment structure 

As stated above, “Classic” segments have a 4-byte header, the first two bytes being the off¬ 
set from the beginning of the jump table of the entry for the first routine in the segment, and 
the second two bytes being the number of jump table entries for the segment. 32-bit seg¬ 
ments have a considerably longer header and contain relocation information. That a seg¬ 
ment is of the 32-bit persuasion can be determined from its first word, which matches the 
“version” field in the second jump table entry, namely $FFFF. The second word is $0000. 
The next longword is the byte offset from A5 of the first “Classic” or near jump table entry. 
This is followed in turn by longwords giving the number of near entries, the byte offset 
from A5 of the first 32-bit jump table entry, and the number of 32-bit entries. The next 
four longwords contain, respectively, the offset from the segment start of the relocation 
information for A5-relative references, the current A5 value used for relocating these refer¬ 
ences, the offset from the segment start of the relocation information for segment-relative 
references, and the segment load address used for relocating these references. Finally, 
there is a longword containing zero that is reserved for future use. Following this header 
is the code, the A5 relocation information, and the segment relocation information. This is 
shown in the following diagram (The order of the shaded items is subject to change.): 
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■ Segment structure 


$FFFF 

$0 

$0000 

$2 

A5 offset of 16-bit 
referenced entries 

$4 

Number of 16-bit 
referenced entries 

$8 

A5 offset of 32-bit 
referenced entries 

$C 

Number of 32-bit 
referenced entries 

$10 

Offset of A5-relative 
relocation info 

$14 

Current value of A5 

$18 

Offset of segment- 
relative reloc info 

$1C 

current segment 
location 

$20 

$0000 

(reserved ) 

$24 

Cocfe . 


ihlorm^tion li 


Segment relocation 
ihfprmation 
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Relocation information format 


The relocation information is simply a consecutive list of offsets between longwords that 
need to be relocated at load time, beginning with the offset of the first such longword from 
the start of the segment Some data compression has been used in recording this informa¬ 
tion. Because instructions start at even addresses, it suffices to record the offset values 
divided by two. In the table below, the various encodings are shown as bit strings. The 
portions denoted by “bbb...” give, when doubled, the desired offset values. 

■ Relocation information 


relocation item 

interpretation 

00000000 00000000 

end of relocation information 

Obbbbbbb 

offsets between $02 and $FE 

lbbbbbbb bbbbbbbb 

offsets between $0100 and $FFFE 

00000000 lbbbbbbb 

bbbbbbbb bbbbbbbb 

bbbbbbbb 

offsets between $00010000 and $FFFFFFFE 


Signal handling in MPW tools 

The MPW 3.2 A1 Release Notes stated a requirement that tools provide their own handling 
of the SIGINT signal (command-period) if any “far” option had been used in building the 
tool. This is no longer necessary, because the Shell will now remove the Segment Loader 
patches after termination of the tool. 


MPW 3.2 Run-Time Architecture 
Enhancements 

Release Notes 

13 Copyright Apple Computer, Inc. 

1990-1991. All rights reserved. 










Run-time support 


A Important Developers are cautioned that the material in the re m ainder of this 
document will probably change in MPW versions after MPW 3.2 a 


Overview 

This section discusses a set of interfaces and libraries for working with the “32-Bit 
Everything” run-time environment Addressed particularly are applications and/or 
debuggers which use the _Launch or _Chain traps, or patch the _LoadSeg trap. 

Files associated with this section are: 

{Libraries}RTLib. o Library that implements the interface; 

{ c includes} RTLib. h C and C++ declarations; 

{ p interfaces} RTLib. p Pascal declarations. 


Run-time interface 

There are two kinds of programs that utilize the run-time interface: applications which need 
knowledge of the environment in which they are executing and resident debuggers which 
need to know about another application’s environment. 

♦ Note: The calls and data structures to follow are shown in C. Pascal equivalents are to 
be found in RTLib.p. 


The “32-Bit Everything” run-time interface consists of a single procedure call: 

pascal OSErr Runtime (RTPB* runtime_jparms) ; 

The operation to be performed is determined by the value of the first member of the 
structure rtpb. rtpb has the form: 
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struct RTPB { 

short fOperation; 
void* fA5; 
union { 

RTGetVersionParam fVersionParam; 
RTGet JTAddrPa ram fJTAddrP a ram; 

RTSetSegLoadParam fSegLoadParam; 
} fRTParams; 

} ; 

typedef struct RTPB RTPB; 


The first member, f operation, can have any of the following values: 


kRTGetVe rsion 
kRTGetJTAddres s 
kRTSetPreLoad 
kRTSetSegLoadErr 
kRTSetPostLoad 
kRTSetPreUnload 
kRtPreLaunch 
kRTPostLaunch 


kRTGetVe rsionA5 
kRTGetJTAddressA5 
kRTSetPreLoadA5 
kRTSetPreLoad 
kRTSetPostLoadA5 
kRTSetP reUnloadA5 


Those operations whose name ends in “A5” require a value for the second member, f as, 
which is the address of an “A5-world.” The similarly-named operation without the “A5” 
uses the current value of A5 as this address. 


The third member, fRTParams, is a parameter block consisting of one of three structures 
holding parameters for the appropriate operation. The details for each structure are in¬ 
cluded with operation’s description. 

Possible errors returned from Runtime include: 


Error 


Description 


eRtNoErr 
eRTInvalidOP 
eRTBadVersion 
eRTInva1idJTPt r 


(success) 

Invalid operation 

Not 32-bit everything run-time 

Invalid jump table pointer 


Run-time operations 

kRTGetVersion, kRTGetVersionA5 

Return the run-time version number for the current (or specified) A5-world. 
The fRTParams structure used with these operations is: 


MPW 3.2 Run-Time Architecture 15 Copyright Apple Computer, Inc. 

Enhancements 1990-1991. All rights reserved. 

Release Notes 














struct RTGetVersionParam { 
unsigned short fVersion; 

}; 

typedef struct RTGetVersionParam RTGetVersionParam; 


f A5 is used only for RTGetversionAS to specify the A5-world. This field is not used for 
RTGetVersion. 

fVersion holds the returned version number. Current version numbers are: 


Version No. 


Description 


$0000 'Classic' world. 

$ffff 32-Bit Everything world. 


kRTGetJTAddress, kRTGetJTAddressA5 

Return the address of the code that the specified jump table entry points to for the current 
(or specified) A5-world. 


The f RTParams structure used with these operations is: 


struct RTGetJTAddrParam { 
void* f JTAddr; 
void* fCodeAddr; 

}; 

typedef struct RTGetJTAddrParam RTGetJTAddrParam; 


f JTAddr points to a given jump table entry. Pointing to a non-valid jump table entry will 
return an unpredictable result. 

f A5 is used only for kRTGet JTAddressAS to specify the A5-world. This field is not used 
for kRTGetJTAddress. 

The code address is returned in fCodeAddr. Zero is returned if the segment is not loaded. 
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Segment Loader hooks 


The operations kRTSetPreLoad, kRTSetSegLoadErr, kRTSetPostLoad, 
kRTSetPreUnioad, and the operations of the same names with a trailing “A5” enable 
programs to acquire control in the case of error, or at pre-LoadSeg, post-LoadSeg, and 
pre-UnloadSeg times. They do this by specifying, for each of the above cases, a user 
handler to replace the (dummy) user handler that exists in the patched Segment Loader. 

The fRTParams structure used with these operations is: 


struct RTSetSegLoadParam { 

SegLoadHdlrPtr fUserHdlr; 

SegLoadHdlrPtr fOldUserHdlr; 

}; 

typedef struct RTSetSegLoadParam RTSetSegLoadParam; 


fUserHdlr is a pointer to the user handler to be called at the time indicated by the opera¬ 
tion. A pointer to the replaced user-handler is returned in foiduserHdir. This pointer can 
be used at a later time to reinstall the original handler. 

A user handler is defined as follows: 

typedef pascal short (*SegLoadHdlrPtr)(RTState* state); 

User-handlers may return a result code of type short. For now the result code is ignored 
by the segment loader except in the case of the error-handler (see Take an actionl 


A Important User-handlers must be defined within a segment that will be loaded in 
memory when the handler is invoked. This will most commonly be the 
main segment Also, a user-handler should not make any calls to func¬ 
tions within an unloaded segment because this may result in a system 
crash, a 

f as is used only for A5 operations and contains the value of register A5 for the specified 
A5-world. 


The RTState structure is used to pass information about segment loader operations to the 
user-handler. It has the form: 
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struct RTState { 
unsigned 


short 

fVersion; 

// run-time version 

void* 

f SP; 

// SP: &-of user return 



// address 

void* 

fJTAddr; 

// PC: &-of jump table entry 

long 

fRegisters[15] ; 

// registers D0-D7 and 



// A0-A6 

short 

fSegNo; 

// segment number 

ResType 

fSegType; 

// segment type (normally 



// 'CODE 1 ) 

long 

fSegSize; 

// segment size 

Boolean 

fSeglnCore; 

// true if segment is in 



// memory 

Boolean 

fReservedl; 

// (reserved for future use) 

OSErr 

fOSErr; 

// error number 

long 

fReserved2; 

// (reserved for future use) 


}; 

typedef struct RTState RTState; 


fversion is the version number of the current “32-Bit Everything” run-time world. 

f sp is the current stack pointer when either _LoadSeg or unioadSeg was executed. In the 
case of _LoadSeg, if the jump table entry was reached via jsr, f sp is a pointer to the user 
return address. The value at this SP may be modified within the error handler to change the 
return address if a “continue” action is taken (see Take an action) . This is not recom¬ 
mended since there may be no user return address on the stack (see discussion below on 
stack contents). In the case of unioadSeg, f sp points to the return address from the 
UnioadSeg call. 

f jTAddr points to the jump table entry called by the user code prior to the _LoadSeg call. 

In the case of unioadSeg it is the jump table entry pointer passed to unioadSeg. This field 
may be edited by the error handler to provide a different point of re-entrance when issuing 
the “retry” action (see Take an action) . 

It is important in the “32-Bit Everything” world that nothing be assumed about the actual 
layout of the jump table entry, since the format may change in new versions. 

f Registers is an array of longs which contains the register values at the time _LoadSeg 
was called. The registers are saved in the order DO through D7, then AO through A6. 

f segNo and f SegType contain the segment’s resource type and id. f segType will nor¬ 
mally be 'CODE', but this may change in the future. 

f SegSize contains the segment's size. 

If f SeginCore is true, the segment is already in the heap, but not locked down. (If the 
segment is resident, no memory needs to be allocated for it). 
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fosErr contains an error number. This field is valid only when the structure is passed to 
an error handler. 

Modifications to the RTState structure are ignored in all cases except when the f jTAddr 
field is altered by the user error handler. 

Operations 

kRTSetPreLoad, kRTSetPreLoadA5 

Arrange for the function fuserHdir to be called by the segment loader just before a seg¬ 
ment is loaded. The user’s pre-load handler replaces the original pre-load handler, and a 
pointer to the old handler is returned in f oiduserHdir. A pre-load handler could be used 
to ensure that enough memory is available for a segment to be loaded. When the handler 
returns, a segment load attempt is made. If an error occurs during the load, the error han¬ 
dler is invoked. 

kRTSetSegLoadErr, kRTSetSegLoadErrA5 

Arrange for the function fuserHdir to be called if a segment load fails. The user's error 
handler replaces the old error handler, and the address of the old handler is returned in 

fOldUserHdlr. 

Upon entering the error handler the stack looks like: 



user parameters 
(optional) 



user return 
address (optional) 

J 



\ 


error handler result 


8 (SP) 

4 (SP) 

address of 

RTState structure 


(SP) 

error handler 
return address 

J 




pushed by user 
code 

(optional) 


SP at time of 
LoadSeg 


present on stack when 
error handler gets 
control 
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Items on the stack that are labelled optional may in some cases not actually appear. For in¬ 
stance, a simple jmp to a jump table entry would not have pushed the user parameters and 
return address. 

The word at 8 (SP ) is the space reserved for the error handler’s action code. 

The value at 4 (SP) points to the RTState structure which provides information about the 
failure. 

The value at (SP) is the return address from the error handler. This may or may not be 
used depending on whether the error handler performs a long jmp to restore control to the 
application (see Retreat) . 

The error handler should examine the RTState structure and take appropriate action (e.g. 
release some memory, etc.). It then can exit in one of two ways: 

■ Take an action . Return an action code on the stack for the segment loader to act upon, 
and return. Current action codes are: 


Value Action 

kRTRetry Retry 

This restores the stack to it's original state 
prior to the _LoadSeg and re-executes the 
jump table entry. If all goes well, execution 
will continue as planned. If f jTaddr in 
RTState was modified, execution will 
resume at the new address. 

Note that unless preventative measures are 
taken (e.g. a maximum retry count) using 
this technique can lead to an infinite loop if 
retrying the load always fails. 

kRTContinue Continue 

This restores the stack to its original state 
prior to LoadSeg and sets the PC to the 
user return address in the stack. This is 
dangerous since a return address may not 
exist. 

Any other value will result in the system error, dsLoadErr, a segment loader error. 


MPW 3.2 Run-Time Architecture 20 Copyright Apple Computer, Inc. 

Enhancements 1990-1991. All rights reserved. 

Release Notes 









■ Retreat! Use long jmp (or an equivalent) to pass control to another error handler, set up 
in a parent stack frame. This handler can attempt damage control (e.g. try to save the 
document, alert the user and quit). 


kRTSetRreUnload, kRTSetPreUnIoadA5 

Arrange for the function fuserHdir to be called prior to unloading a segment The address 
of the original handler is returned in f oiduserHdir. 

The meaning of the fields within the RTState structure vary some from their use with the 
other handlers. Specifically, f sp points to the return address from the unioadSeg call and 
f jTAddr is the address of die jump table entry used as the parameter for unioadSeg. The 
remaining fields are the same as described above. For debuggers, the pre-unload handler 
can be used to uninstall breakpoints within a segment before it is unloaded. 


Examples 

{*-*} 

{* example.p *} 

{* An example tool which installs a pre-load handler and uses it *} 

{* to print information about the segment. *} 

{* *1 

{* pascal -model far example.p *} 

{* link -model far -w -t MPST -c 'MPS 1 -o examplep d *} 

{* example.p.o {Libraries}RTLib.o {Libraries}Interface.o 3 *} 

{* {Libraries}Runtime.o {PLibraries}PasLib.o *} 

{* examplep *} 

{*-*} 


PROGRAM Example; 

USES 

RTLib, Toollntf, Types; 


VAR 

p: RTPBPtr; 

param_block: RTPB; 

error: OSErr; 

{$S One} 

PROCEDURE one; 

BEGIN 

{ 

do something 

} 

END; 

{$S Main} 
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FUNCTION preloadjiandler(state: RTStatePtr): INTEGER; 

BEGIN 

{ 

print segment information 

} 

WRITELN (' segno = 1 , state''. f Segno) ; 

WRITELN ( 1 segtype = 1 , state''. fSegType) ; 

WRITELN( 1 segsize = state*.fSegSize); 

IF (state''.fSeglnCore) THEN WRITELN('incore = yes’) 

ELSE WRITELN( 1 incore = no 1 ); 
preload_handler := 0; 

END; 

BEGIN 

{ 

load writeln segment so that the pre-load handler does not 
invoke another call to _LoadSeg 

} 

WRITELN( 1 load writeln segment 1 ); 

{ 

load the handler 

} 

p := @param__block; 

p*.fOperation := kRTSetPreLoad; 

p*.fUserHdlr := Ptr (@preload__handler) ; 

error := Runtime(p); 


{ 

load the segment 

} 

one; 

END. 

/* - */ 

/* example.c */ 

/* An example tool which installs a pre-load handler and uses it */ 

/* to print information about the segment. */ 

/* */ 

/* c -model far example.c */ 

/* link -model far -w -t MPST -c *MPS 1 -o examplec d */ 

/* example.c.o {LibrariesJRTLib.o {Libraries}Interface.o d */ 

/* {Libraries)Runtime.o {CLibraries}StdCLib.o */ 

/* examplec */ 

/*-*/ 


#include <stdio.h> 

#include <types.h> 

#include <RTLib.h> 

tpragma segment One 
one () 

{ 

// 

//do something 

// 

> 
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fpragma segment Main 

pascal short preload__handler (RTState* state) 

{ 

// 

// print segment information 

// 

printf("segno = %d\n", state->fSegNo); 

print f ("segtype = %.4s\n" f & (state->f SegType) im¬ 
print f("segsize = %d\n", state->fSegSize); 

if (state->fSeglnCore) printf("incore = yes\n"); 
else printf("incore = no\n”); 
return(0); 

) 

main () 

{ 

RTPB param_block, *p; 

OSErr error; 

// 

// load printf segment so that the pre-load handler does not 
// invoke another call to _LoadSeg 
// 

printf("load printf segment\n"); 

// 

// load the handler 

// 

p = &pararn_block; 
p->fOperation = kRTSetPreLoad; 

p->fRTParam. fSegLoadParam. fUserHdlr = (void*) &preload__handler; 
error = Runtime(p); 

// 

// load the segment 

// 

one(); 

) 


Calling Launch and Chain 

MPW does not provide glue or interfaces for calling _Launch or _chain; application 
writers must call the traps themselves from assembly or assembly-language inlines. 
However, the “32-Bit Everything” environment requires some hand-holding in order to 
survive a call to _Launch. 

Under 32-Bit Everything, a call to _Launch must be wrapped between two calls to 
Runtime using the operations kRTPreLaunch and kRTPostLaunch: 
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IMPORT 

(Runtime): CODE 



MOVE.W 

tkRTPreLaunch,-(SP) 

f 

push fOperation 

SUBQ.W 

#2, -(SP) 

9 

room for result 

PEA 

2 (SP) 

/ 

push ptr to RTPB 

JSR 

Runtime 

r 

prepare for launch 

^Launch 


9 

attempt a launch 

MOVE.W 

#kRTPostLaunch,-(SP); 

push fOperation 

SUBQ.W 

#2, - (SP) 

/ 

room for result 

PEA 

2 (SP) 

9 

push ptr to RTPB 

JSR 

Runtime 

9 

post-launch housekeeping- 


The only parameter used from the RTPB structure is fOperation. The pre- and post-launch 
operations do not require a parameter block for fRTParams. 

Note that DTS says that you should never call the _Chain trap, since it is not implemented 
by MultiFinder. However, if you find it necessary to call _Chain, then wrap it in the same 
manner as that needed by JLaunch. 
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MPW 3.2 “411” Help 
Release Notes 


About “411” 


“411” provides a way for Macintosh developers to achieve rapid retrieval of software de¬ 
velopment information while using Apple's MPW development system. The access can be 
via menus and command keys or from command line entries. The software development 
information includes language-specific Inside Macintosh documentation, Tech Notes, 
MPW command descriptions and Resource information. In addition a facility for automatic 
insertion of Toolbox call templates is provided. Large cross reference index files 
(. windex) may be optionally used to provide an extremely rapid search of the documenta¬ 
tion for any desired word. In the absence of these files, the same search may be made, but 
it will be a linear search and therefore will be relatively slow. 

“411” can also be customized and extended and new information can be added. The help 
files of “411” may be either local or on a shared file server. 


Setting up “411” 

“411” consists of a installation instructions file (Read Me First) , a special UserStartup 
script (UserStartup*Help), an installation script (instaii4ii), and a set of help files 
along with their . index and . windex files. It makes use of a new MPW tool. Get, which 
was written to support “411” but can be used independently. The “411” folder holds the 
help files, their index and cross reference index files and a ‘Tools” folder. 
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An important decision to make in setting up “411” is whether to place the “411” Help files 
on a server or on your local hard disk. Since these files are large (over 16 Meg total) some 
thought should go into deciding which files to use and whether to transfer them to your 
hard disk or, if you are connected to a network, to a file server. The most obvious candi¬ 
date for removal is either CIncludesHelp or PInterfacesHelp. If you are not developing in 
both C and Pascal, one of them will probably not be needed. Less obvious, but more sig¬ 
nificant candidates for removal are the .windex files. These files are not required, but sig¬ 
nificantly speed up the cross reference search that is done when selecting the “Search” 
menu item. Placing the help files on a local hard disk will provide better access speed but 
will use significant disk space. If you have access to a file server and several persons want 
to access “411” Help, it may be best to move the “411” folder to the file server. 

Set up “411” by writing the following two commands to your MPW Worksheet and exe¬ 
cuting them: 

<rls>:Install411 <info> 

Execute "{ShellDirectory}"UserStartup•Help 

where <ris> denotes the path to the “411” files on the release medium and <info> denotes 
the volume on which the user wishes the “411” Help files to reside. If <inf o> is omitted, 
the installation will be to the volume that begins the path <ris>. (In this latter case, the 
data files are not duplicated because they are already residing in the desired place.) 

For example, if “411” were to be released in a folder named 4iistuf f on a CD named mpw 
3 . 2 Release, and the user wanted “411” to be installed on a volume named HeipMe, then 
the commands to be executed would read: 

'MPW 3.2 Release:411Stuff:Install411' HeipMe: 

Execute ”{ShellDirectory}"UserStartup*Help 

The effect of the first of the above commands is to create the folder HeipMe: 4ii : and to 
copy to it all of the “411” files. It then, additionally, copies the new Get tool to the user’s 
MPW Tools folder, copies userstartup*Heip to the MPW folder, and creates a folder 
called Help Folder in the MPW folder. This latter folder contains at this time a file called 
Heip_Foider whose contents is the single line: HeipMe : 411 :, i.e. the name of the folder 
containing the “411” information. The effect of the second of the above commands is to 
add the “411” menu to the menu bar, and to add one more file to the Help Folder, a file 
called Heip_Fiies which contains the names of all of the “411” data files in the order in 
which they will be interrogated, e.g.: 

HeipMe:411:CIncludesHelp 
HeipMe:411:InsideMacintoshHelp 
HeipMe:411:MPWHelp 
HeipMe:411:PInterfacesHelp 
HeipMe:411:ResourcesHelp 
HeipMe:411:TechNotesHelp 
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♦ Note: Because of their large size, the cross reference files (. windex) are not installed 
automatically. If you wish to use these files, drag their icons to the desired folder. 


Using the “411” Help menu 


“411” works only from within the MPW development environment. When “411” is prop¬ 
erly set up, there should be a 411 menu on the MPW menu bar. If there has been no 
change to the userStartup»Heip script, the Help menu looks like this: 


■ 411 Menu 


Build Format Directory 
^ HD:MPlll:lUorksheet I 


-41 1 


Contents 
Look up 
Template 
Show Keys 
Search 


Set First File 
Set 411 Files 


HE 

HI 



Edit 411 Files... 


About 411... 


The menu items Look up and Template search all of the files listed in Heip Fiies; 
the items Contents, Shorn Keys, and Search look only at the first file in the 
Heip_Fiies list. This first file is known as the currently selected file. It can be changed 
by using the Set First File menu item. 


Contents 

This menu item lets you see a list of the Help file’s table of contents. For example, if the 
CIncludesHelp file is the currently selected Help file, then selecting the “Contents” menu 
item, causes a list of the ToolBox managers to appear in the Help window. 
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HelpMe:411:CIncludesHelp 


Look up... "Help 


Appletalk.h 
Controls.h 
CursorCtl.h 
Desk.h 
Deskbus.h 


FixMath.h 
Fonts.h 
Globals 
Graf3D.h 
HyperXCmd.h 


Palettes.h 
Perf.h 
Picker.h 
Printing.h 
Quickdraw.h 


Serial.h 
ShutDown.h 
Slots.h 
Sound.h 
Start.h 


Note that you can obtain the same information by selecting the key word "Help" (or the 
name of the help file, e.g. CIncludesHelp) and then selecting the Look up menu item. 


Look up (16 E) 

This menu item lets you look up information stored in the help files; the search starts with 
the currently selected file (See Set First File...). For example, if you choose (see 2 
below) the word Findwindow and then select the Look up menu item (or type 8§e) the 
following information will appear in the Help window: 


HelpMe:411 .-CIncludesHelp Look up... "findwindow” 


short findwindow(Point *thePoint,WindowPtr *theWindow); 

Type: Function 

File {CIncludes}Windows.h 

Trap Number A92C 

InsideMacintosh Reference: Findwindow function 1-287, P-35, 114, 170 
Findwindow procedure V-208 

[Macintosh Plus, Macintosh SE, Macintosh II] 

When a mouse-down event occurs, the application should call Findwindow 
with thePt equal to the point where the mouse button was pressed (in 
global coordinates, as 


Thus, to get help for a given key word: 

1) Choose the Help file you want information from by using the Set First File... menu 
item to make the desired file the first file (currently selected file) in the help file list. 
(Skip this step if the help file is already selected, or if the order of search does not mat¬ 
ter.) 
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2) Click on a word in the active window. You may want to type in the word you want to 
look up instead. If the item is just one word, it will be automatically selected if the 
insertion point is adjacent to or within the word. Only if a multiple word item is to be 
looked up is it necessary to do a manual selection of the entire item. (Note: the means 
you don’t have to double-click. Also you don’t have to type the entire word, just 
enough letters to allow 411 to distinguish between the word you want and any other in 
the current Help file.) 

3) Select the menu item Look up or type He. This triggers a search through the help 
files, in the order in which they are listed, looking for the selected key word. If the 
search is successful then a window named Help (a file in the MPW directory) is opened 
and the information associated with the key word is displayed, along with an indication 
of the file in which the key word was found. 

Remember, the Look up menu item simply looks for the current selection in the active 
window. 

Since numbers are keywords only in TechNotesHelp, selecting a number will retrieve the 
Macintosh Technical note of that number. 

The header, which is placed above the “Contents” information, shows the help file that was 
used. To the right of the file name is a message indicating the key word on which the 
search was made. A mark is set to this (selected) key word in the file Help to aid the user 
in subsequent scanning of Help for previously gathered information. 

A slight modification of userstartup*Heip causes the header to list all the “411” files in 
the order in which they are searched, with the words on the right (Look up...) printed on 
the line bearing the name of the file in which the item was actually found. (See 
Customizing “411” below.) 


Template (8§ 1) 

This menu item lets you replace a toolbox function call such as FindWindow with the 
template for that function. For example if you were to select “FindWindow” and choose 
the Template’ menu item (or type Hi), then your "FindWindow" selection in the Active 
window would be replaced by: 


short myVariable = findwindow((Point *)thePoint,(WindowPtr *)theWindow); 

Both C and Pascal templates are available. Use Set First File... on the 411 menu to 
choose a language by selecting either CIncludesHelp or PInterfacesHelp. 
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Show keys... 

This menu item lets you list all of the keys in the currently selected help file which begin 
with the word you have selected in the Request dialog. For example, selecting this menu 
and then typing the two letters “fs” when CIncludesHelp is your current (first listed) help 
file, produces a list of all of the HFS calls that begin with “FS”, i.e. FSClose,... 


Search... 

This menu item lets you search the currendy selected help file for all occurrences of the 
word you have selected. The result is a list of names (keys) whose data records contain the 
word. On a large Help file, e.g. CIncludesHelp, this can take a minute or more. Only the 
current (first listed) help file is searched even if no data record containing the word is 
found. If your help folder contains a cross reference file (. windex) for the Help file, the 
time to search is reduced to just a few seconds. 


Set First File... 

This menu item lets you choose a help file to be the currently selected file. A dialog win¬ 
dow shows a list of all help files, and you are invited to make a selection. The selected file 
then becomes the first file in the list that appears in the file Heip_Fiies. It is then known 
as the currently selected file, and, until you again reorder the list, is the initial target of all 
Look up. Template, and Contents requests, and the only file used by Show 
Keys and Search. The Help window opens, displaying the contents list of the selected 
file. 


Set 411 Files... 

This menu item presents a standard file dialog from which to locate a help folder. If a help 
folder is selected then all the files in the folder that end in the word help are placed in the 
list of files to search (in Heip_Fiies). Note that this will remove any existing files from 
the list.. 
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Edit 411 Files 


This menu item open the Heip_Fiies window, which contains a list of all the help files 
that “411” knows about. The list may be edited and then saved. Note that each line speci¬ 
fies a path to a single help file. 


About 411... 

This menu item displays the credits and then does a lookup in the MPWHelp file for the 
key “About 411”. 


Customizing “411” 

There are several ways in which “411” can be customized by modifying the 
UserStartup*Help script: 

■ If you are using a file server and want the script to call the MPW Choose tool to mount 
the file server when MPW is launched, set the script variables Heip_server and 
Guest . Set the former to the desired zone:server:volume pathname, and set the latter to 
1 if want to log onto the server as an AppleShare “guest.”. Note: This requires the 
Choose tool from MPW 3.2 or later. 

■ If you wish to add or change command keys in the menu, simply edit the AddMenu 
commands in the userStartup»Heip script. For example, the line 

AddMenu 411 "Look up/1" 

in the script could be changed to: 

AddMenu 411 "Look up/7" 
to change the function key to 8S7. Alternatively, 

AddMenu 411 "Look up" 

removes the function key associated with the Look up menu item entirely. 

■ If you wish to change the name of the “411” menu, modify the argument of the AddMenu 
command. For example, you can change the menu name “411” to “MyMenu” by 
changing all occurrences Of AddMenu 411 ... to AddMenu MyMenu. .. in the 
UserStartup*Help Script 
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If you wish all help files to be listed in the header, change the script so that it sets the 
value of the variable headerstyle to -h (the default is -h2). 


Using the Get Tool 

The retrieval of information through the “411” Help menu is based upon calls to the MPW 
Get tool. The calls that are used by “411” can be seen in the file userStartup*Heip. If 
you choose, you may instead call the Get tool directly or from your own script. 

(See the section on Get in the MPW 3.2 Tools/Scripts Release Notes.) 


Adding your own help to “411” 

Help files used by the Get tool are ordinary MPW Shell document files whose names end 
with “Help” and that have an internal organization which is recognized by the Get tool. 

The requirements are that a Help file consists of a set of records, each record in turn con¬ 
sisting of one or more fields. Each record must start with the field tag $ky (“ae” is option-’) 
followed by one or more words separated by carriage returns. The search of the help file is 
made on the key words. All other fields are various categories of information to be re¬ 
trieved. Field tags must be the first item on a line, and are separated from the following 
material by one or more spaces. Field tags are case sensitive. Each field is terminated by 
the appearance of a new field tag. The record is terminated by the next $ky tag (or end of 
file). 

Example: 

aeKY Keyl 
Key2 
Key 3 

aeC This is a comment 
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The various tags other than ®ky are used to put the information to be retrieved into cate¬ 
gories. The most neutral of them is aec, which is used for general textual matter. These 
tags in some cases modify the behavior of Get. For example, the tag ®dt, which is used 
for templates, precedes data which will be retrieved if and only if Get is called with the -t 
option. This is used in the implementation of the “template” menu item. Other tags cause 
some boiler plate to be emitted prior to the text in the data base. For example, the tag *ri is 
used for fields that contain chapter and page references to Inside Macintosh. The text 
following the field tag will have inserted before it the cosmetic text: “insideMacintosh 
Reference: 

Field Tag Codes: 


®ky Key word or set of key words separated by carriage returns. This field denotes 
the beginning of a “411” record and the words in this field are the record's 
names, i.e. the words used as keys for retrieval of the record’s data. 

*kl Key word List. This is typically used in conjunction with the key “Help” to 
list, as a table of contents, all of the key words in the file. 

aeFa File name of Assembler include file. 

aeFc File name of C header file. 

asFp File name of Pascal Interface file. 

«f Used for the names of files which are not interfaces. 

aeT Type of the item: function/structure/constant/etc. 

aeD Formal declaration of the item: function, procedure, or structure. 

aeDT A template for calls of procedures and functions. 

aec Commentary. This is general textual information, generally lengthy compared 
to that associated with the other tags. 

aeR Reference to... Used for references other than to Tech Notes and Inside 
Macintosh. 

aeRi Reference to Inside Macintosh. This is usually a chapter and page reference. 

aeRT Reference to Tech Note. This is usually a reference by number. 

aeTN Trap Number. This is used to annotate function that are in-line trap calls. 

aeMM Routine may move or purge memory. This tag cause issuance of the preceding 

warning. 
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When the Get tool is executed, it first retrieves the byte offset of a key word from the index 
file, positions to the asKY line in the help file, and then reads all of the following lines until 
another aeKY typed line is encountered. Get then outputs the record, after first removing 
the field tag codes from each field. Therefore, if the contents of a help file are altered in 
any way, it is necessaiy that the index be rebuilt This is handled automatically by the Get 
tool, which puts up a dialog stating that the index needs to be rebuilt and requesting 
permission. In ordinary circumstances, this dialog should be answered affirmatively. 


About the files in your “411” folder 


The ”411" folder contains the following files: 

: 411: 

Install411 

CIncludesHelp 
CIncludesHelp.index 
CIncludesHelp.windex 

InsideMacintoshHelp 
InsideMacintoshHelp.index 
InsideMacintoshHelp.windex 

MPWHelp 
MPWHelp.index 
MPWHelp.windex 

PInterfacesHelp 

PInterfacesHelp.index 

PInterfacesHelp.windex 

ResourcesHelp 
ResourcesHelp.index 

ResourcesHelp.windex 

TechNotesHelp 
TechNotesHelp.index 
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# file. 
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TechNotesHelp.windex 


:411:Tools: 

Get 

UserStartup # Help 


# the TechNotesHelp cross 

# reference index file. 

# the Get MPW tool - used to 

# look up help info. 

# the "411" UserStartup script. 


Files created by “411” 


The following files are created by the userstartup*Heip script, either at startup time, or 
as the result of execution of menu items created by the script They all reside in the folder 

"{MPWJHelp Folder:" 


Help 

Help_Folder 


HelpJFiles 


Help__Temp 


# your "411" Help window. 

# contains the "411" path name 

# (path name to help data and 

# index files) 

# contains the list of all help 

# files (full file names including 

# path) 

# temporary file used by the "411" 

# menu 
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MPW 3.2 Appendix A 
Release Notes 


StreamEdit—scriptable text editor 

Syntax StreamEdit [ -e string ] 

[ -d ] 

[ -o file ] 
l -s scriptFile ] 

[ -set variablei=value] ] 

[ file... ] 

Description 

StreamEdit is a non-interactive text editor similar in function to the Unix® tool sed} 
Providing scriptable text matching and editing operations, it is useful for making repetitive 
changes to files, for extracting information from text files, or as a filter. 

StreamEdit takes a script and a set of input files (or standard input, if no input files are 
specified) and, to each line of input in turn, applies each statement in the script, writing 
the output to standard output or the specified output file. 

A statement consists of an address or address range followed by one or more commands. 
The commands in a statement apply to those input lines that match the address or 
address range. Addresses are specified either numerically, by context matching using 
regular expressions, or by simple boolean functions of the above. A command may have 
parameters in the form of options and text strings. The commands, in general, cause 
modification of the input line, and may furthermore cause text to be inserted before or 
appended after the input line. 

The -d option profoundly affects the editing process in that it filters out the initial input 
lines so that they are not sent to the output except when a particular command explicitly 
causes such transmission. 

The script is specified in the command line by one or more -e or -s options. (Using the 
-s option, the script comes from the named file; using the -e option, it is the string argu¬ 
ment to the option.) If more than one script is specified, the resulting script is the con¬ 
catenation of all the scripts. If no script is specified and -d is not used, the action is sim¬ 
ply to copy the input lines to the output. 

A script consists of a series of statements of the form: 

address-expression command [ ; command ... ] 

In a script file, statements and commands are separated by newlines or semi-colons. If 
the script is a text string (-e option), only the semi-colon may be used. All the commands 
following a particular address expression are executed when the address of the line being 
processed matches the address expression. 


*It is not compatible with Unix® sed or awk. 
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Note that strings must be quoted. Therefore, a command such as 



StreamEdit -s -d scriptl 
where the contents of scriptl is 


1 print 'I found line 1'; 2 print 'I found line 2' 
should be written, using the -e option, as 


StreamEdit -d -e "1 print 'I found line 1'; 2 print 'I found line 2' 


A command takes the form: 


command-name [ text-arguments ... ] 


Address expressions may span multiple lines; arguments to commands are terminated by 
either newlines or semi-colons. 

Address expressions, commands and command arguments are described below. 

Empty statements and commands are legal and are ignored. However, the first com¬ 
mand following an address expression may not be empty. Comments begin with a sharp 
sign (#). Semi-colons, unless they appear as the first character on a line, are equivalent to 
line breaks as in the Shell, and are used to terminate commands. Newlines (outside of 
strings) may be escaped to extend an argument list. 

If a script line contains a semi-colon in the first column, the entire line is treated as a 
comment by StreamEdit. This allows writing StreamEdit scripts that also contain MPW 
shell commands. See the Examples section for more details. 



Operation 


StreamEdit operates on three buffers, called the edit buffer, the insert buffer and the ap¬ 
pend buffer. For each line of text in the input, StreamEdit performs the following steps: 

[1] Read the next input line into the edit buffer. Clear the insert and append buffers. 

[2] Evaluate each address expression specified in the script (in the order in which it 
appears) with respect to the edit buffer's current contents. If an address expres¬ 
sion matches, then execute the actions associated with the expression. 

The append command sends its argument to the append buffer; the insert sends 
its argument to the insert buffer. All other commands either affect the edit buffer 
or directly write to the output file. 

[31 When all address/action pairs in the script have been evaluated, concatenate the 
insert, edit and append buffers and write them to the output file. 

Note that some commands (e.g. Replace and Change) can alter the contents of the edit 
buffer; these changes persist, possibly affecting subsequent address matches. 
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Addresses 


An address takes one of the following forms (operators are listed in decreasing precedence): 


( address ) 

! address 

address && address 

address || address 

address , address 

/regular expression / 


Parenthesis are used to control precedence; 

NOT operator; the address must not match; 

Both addresses must match; if the first address 
fails, the second address is not examined; 

Either address may match; if the first address 
succeeds, the second address is not examined; 

Matches the inclusive range of lines begun when 
the first address matches, and ended when the 
second address matches (this is meant very 
literally; see below); 

Matches any input line containing the expression 
(see the chapter on Advanced Editing in the 
MPW Shell documentation for details; see below 
for extensions to regular expressions); 


N 

$ 

oo 


Considers a match to have succeeded before the 
first input line is read; 

Matches input line number N; 

Matches the last input line; 

Considers a match to have succeeded after the 
last input line is read; 


Parenthesis and the !, &&, II and , (comma) operators may be used to form complex 
address expressions. For example: 

(/trillian/ I I /zaphod/ && /beeblebrox/) && !42 

will match any line containing either the text “trillian”, or both “zaphod” and 
“beeblebrox” (in any order), as long as the line is not the 42 nd input line. And: 

(1,10) && /Copyright/ 

matches a line containing the word Copyright, but only on one of the first ten input lines. 

The range operator can be tricky in several circumstances. This is because it represents a 
two-state system, not a continuous test for a condition. When the condition for the start of 
the range is met, source lines are considered to match up to and including the line at 
which the condition for the end of the range is met. If the first of these is not met, no 
lines in the range will be considered. If the last of these is not met, lines will be consid¬ 
ered to be a match forever! For example, the expression: 

/Copyright/ && (1/10) 

will match the range “/Copyright/ && 1” to “/Copyright/ && 10”; if Copyright 
does not appear on the tenth input line, the range will stay active until the end of the 
input, which is probably not what was intended. If Copyright does not appear on the first 
input line, the range will not be activated at all. 
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Extensions to Regular Expressions 

Regular expressions are the same as those that the MPW shell supports, with the following 
extensions: 

• A regular expression of zero length, specified with two adjacent slashes (//) means 
“the last regular expression matched.” 

Note that the last regular expression matched may be different from the most 
recent regular expression that appears in the script. That is, the short-circuit 
evaluation of the && and I I operators may change the meaning of //. For instance: 

/l/ || 121 replace // "3" -c « 

will replace all occurrences of “1” or “2” with “3” 


• A “q” symbol (generated by Option-C) as the first character in a regular expression 
causes the regular expression to match in a case-sensitive manner (normally 
matches are case insensitive). To use a bullet character (•) to anchor the match at 
the beginning of the line, the bullet must follow the “q” symbol. That is, use: 

/g*foo/ 


and not: 


/•gfoo/ 


# <— Wrong! 


The value of a variable may be referenced within a regular expression by enclosing 
the variable name between < and > symbols (this substitution is very similar to the 
way curly-braces work in MPW Shell scripts). The variable’s value is not treated as a 
regular expression, but rather just a string that must exactly match. An empty vari¬ 
able (a null string) matches nothing — note that variables are empty unless they are 
set. 

For instance, the following script searches for all occurrences of the text “foo”: 

♦ set VAR ”foo" 

/£VAR>/ print 

If the variable match has to be case-sensitive, the regular expression must be case- 
sensitive, as in: 


• set VAR "foo" 
/?<VAR5/ print 


Common Pitfalls 

By far the most common mistake for a beginning StreamEdit user to make is to confuse 
variables and strings in replacement expressions. When not within regular expressions, 
strings must be quoted; an unquoted variable name represents the value of the variable. 
For instance, the statements: 


and 


replace /hum/ dum 
replace /hum/ "dum" 


# the variable dum 

# the string "dum” 
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differ in that the first statement replaces /hum/ with the contents of the variable dum, 
while the second statement replaces /hum/ with the string “dum”. Since variables start 
out empty, if the variable dum has not been initialized then the first statement has the 
possibly alarming action of deleting the /hum/. 


Text Arguments 

Most commands accept text arguments, referred to in the command summary below as 
“text”. These arguments are expanded and concatenated into a temporary output buffer 
and then moved to the destination. Text arguments take the following forms: 


Text Argument Form 

Expansion 

"string" 

The string itself (escape characters are processed, 

'string 1 

and single or double quotes are allowed). 

• 

A period represents the contents of the edit buffer (the 
current input line) minus its newline; 

variable 

The contents of the variable; 

®N 

The marked expression N t from the most recent match; 

-from filename 

The next line of input from the specified file, minus its 
trailing newline (if any). The filename argument may 
be any other text argument form except -n (a string, a 
variable, an ®-variable, etc.). If the filename is empty 
(e.g. an uninitialized variable) the value is empty. 

-n 

Suppress trailing newline at end of expansion. 


Variables are names for strings. Variables are initially empty. Variable names are case- 
ignored C identifiers, that is, [a-zJ[a-zO-9J*. Again, care should be taken not to mistake 
variables for strings. 


Numbers are decimal. Strings are enclosed by single or double quotes. The backslash (\) 
and shell-quote 0) characters may be used to quote special characters within strings and 
regular expressions: 


Quote form 

Expands to 

dn 

\n 

newline 

at 

\t 

tab 

a\ 

\\ 

backslash 

aa 

\a 

shell quote 


Files are named streams of text; the argument to -from or -to may be a string, a variable, 
an “®” variable, or even a -from. It is possible to read a file that is also being written; 
writing to a file does not change the read position. There can be any number of files; 
StreamEdit is not limited by the system’s FCB count. 


Commands 

The underlined portions of each command name below indicate the minimum amount of 
text needed to specify the command. It is guaranteed that future commands will not 
conflict with existing abbreviations. 
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Append [-n] text 

Append the specified text to the append buffer, to be written at the end of the current 
cycle. If -n is not specified, a newline is automatically added to the end of the text. 

$ Append "This line follows the last line of the input" 

42 App -n "This is line 43 ==>" 


Ins ert [-n] text 

Append the specified text to the insert buffer, to be written at the end of the current cycle. 
If -n is not specified, a newline is automatically added to the end of the text. 

1 Insert "This text precedes the first line of the file" 

42 Ins "This is line 42 =*=>" -n 


Change [-n] text 

Replace the contents of the edit buffer with the specified text. If -n is not specified, a 
newline is automatically added to the end of the text. 

42 Change "This is line 42" 

/droid/ Ch "These are not the droids you're looking for" 

Del ete 

Clears the contents of the edit buffer; essentially the same as specifying “Change -n”. 

1,$ Delete 

/• [ dt]*#/ Delete # delete lines that are Shell comments 


Next 

Concatenates and prints the insert, edit and append buffers. Gets the next line of input 
and begins the match-execute-print cycle over again. 

1,/foo/ Next # ignore input until "foo" is found 

Note that Next affects the normal control flow in the script, sometimes with unexpected 
results. Once the Next command has been executed, no further commands in the script that 
match the current line will be executed, because the next line of input is fetched immediately. Note 
also that the printing is independent of the -d option; the buffers will be printed exactly once 
regardless of the presence or absence of -d. 

Ecint [-appendto file | -to file] text 

Print the specified text on standard output, or to file specified by -to or -appendto. The 
text is written immediately (that is, before the insert, edit and append buffers are written). 
If no text is specified, the contents of the edit buffer, is assumed. If -n is not specified, 
a newline is automatically added to the end of the text. 

The -appendto option appends the output of Print to an existing file. If the file does not 
already exist, it is created. 

The -to option directs the output of Print to the specified file. The file is truncated the 
first time it is written to. 


MPW 3.2 Appendix A 
Release Notes 


6 


Copyright Apple Computer, Inc. 
1990-1991. All rights reserved. 




Type 

Input 


Both -append and -to require a filename argument. The filename may be specified by a 
string, a variable, or an ®-variable. If the filename is an empty string (e.g. an uninitialized 
variable) nothing is printed. 

1,10 Print 

1,$ print -to "MyFile" "»> " . 

/ ([a-zO-9] +) ®1/ print -to ®1 
1,$ Pr -to MYVAR 


Replace [-c count] /pattern/ replacement__text 

Replace the pattern in the edit buffer with the specified text. Unlike their behavior in 
other commands, any “®” variables in the replacement text refer to the values set by 
processing the pattern argument to Replace, not the “®” variables in the line's address. 

The count following -c may be a number, or (which specifies an infinite count). 

/42/ replace /42/ "Meaning of Life" 

/42/ replace // "Meaning of Life" # // is the same 

Rep /(©[ dt]*19[-0-9]+)®l([ 9t ]* Apple*) ®2/ ®1 ", 1989" ®2 


Exit [status] 

Stop processing. Nothing more is printed. If a single numeric argument is supplied, it is 
used as StreamEdit's exit status. 

Exit 42 # exit with status 42 

Exit # exit with status 0 


Set [-a | -i] variable text 

Set the contents of the variable to the specified text. No newline is automatically added. 
The -a option causes the text to be appended to the variable's current contents. Likewise, 
the -1 option causes the text to be inserted before the variable’s current contents. 

/•#! ( [a-zA-Z0-9_]+)®l/ Set current_file ®1 

set line . # make copy of current line, sans newline 

set line . "\n" # make copy of current line, with newline 

set -a frog -from "some file" 


Option keyword ... 

A general purpose command that controls the processing of the script and the input text. 
Current keywords are: 

Auto Delete 

Specifying the “auto delete” option is equivalent to appending the command 

/*/ Delete 

to the very end of the script. All input lines will be deleted; the only output will be 
from Print commands. This is also equivalent to the -d command line option. 
This is useful when writing filters or scripts that do not need to copy the input 
lines as a matter of course. 


Tool 

Standard input, if no files are specified. 
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Outputs The result of applying the script to each line of input, directed to standard output unless 
the -o option is specified. 

Also, the results of executing -to file and -appendTo file commands. 


Options 

-e string The string is the script to compile. This option may be used more than once, 
and may be used in conjunction with the -s option. The final script is the 
concatenation of the -e and -s options, in the order specified on the 
command line. Note that string must be quoted. 

-d Specifying this is exactly equivalent to having a command of the form 


/«/ Delete 

as the very last command in the script. It causes all input lines to be deleted; 
the only output will be from Print or Next commands. This is also the same 
as specifying the “Option AutoDelete” command (see above). 

-o file Direct the final output of StreamEdit to the specified file, -o is a “safe” 

option; the destination file is not written until all of the input is read, so the 
output file may be one of the input files. 

-s file Read the specified file and compile the script it contains. This option may be 
used more than once, and may be used in conjunction with the -e option. 

The final script is the concatenation of the -e and -s options, in the order 
specified on the command line. 

-set variablel= value] 

Set the variable to the specified value; this is exactly like using a Set com¬ 
mand, except that the variables are defined before the script is executed. The 
value may be omitted, in which case the variable will be set to the empty 
string. 


Examples 

Extracting the Leaf Part of a File Name 

It is sometimes necessary to extract the leaf part of a complete file path name in a Shell 
script. The StreamEdit expression: 

/ (*»:) * ([—is ] *) ®1/ 

sets the variable ®1 to the part of the file name following the last colon, or to the whole 
file name it doesn’t contain a colon. It could be used in a Shell script as a filter: 

# {MPW}Scripts:FilterLeaf 

StreamEdit -d -e '/(«:)*([-»:] *) ®1/ print ®1' 

For example: 

Echo "The:I:Is:SilentrmyFile" I FilterLeaf 
would print: 

myFile 
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Generating Inlines 

This is a script that generates MPW C or C++ inline function declarations from assembly 
language source. It is far easier and less error-prone than hand-assembly or cut-and-paste; 
even though this script depends on the format of the listing file produced by the MPW 
Assembler, it is better to automate the process. 

The script’s usage is: 

MakeCInline assemblyfile .a >outputFile 
Given assembler input something like this: 


Inline Pascal string copy 
¥ void pascal_string_copy(char* src, char* dest); 



proc 

movem.1 

(SP), A0-A1 


moveq 

#0, DO 


move.b 

(Al) , DO 


bra.s 

82 

Sloop: 

move.b 

(Al)+, (A0) + 

@2: 

dbra 

DO,81oop 


endproc 



We want the filter to produce an inline declaration something like this: 

void pascal_string_copy(char* src, char* dest) = 

{0x4cd7, 0x0300, 0x7000, 0x1011, 0x6002, 0xl0d9, 0x51c8, Oxfffc}; 

The character “¥” in the assembler comment marks the declaration; in principle any 
unique character or string can be used to flag the declaration. 

The script has two parts; the first part contains MPW Shell commands, the rest of the 
script contains StreamEdit statements. 

The MPW Shell part of the script is: 

# MakeCInline — make C assembly language inline declarations 
; asm "{1}" -1 

; StreamEdit -d -s "'which {0}'" "{l}”.1st 
; Delete "{l}".lst "{l}".© 

; exit 

It runs the assembler on the input file, producing a listing which is processed by the rest 
of the script. Then the temporary files are removed and the MPW Shell part of the script 
exits; the Exit command ensures that the Shell doesn’t execute any StreamEdit statements. 

The invocation of StreamEdit here uses an interesting trick; the name of the StreamEdit 
script to execute is, naturally, the name of the currently executing script. So we use 

'which {0}' 

which expands into the name of the currently running shell script. 
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The rest of the file contains a StreamEdit script that processes the assembly listing 
produced above. Here is an example of the assembler’s listing output: 

MC680xx Assembler - Ver 3.2dl 21-Nov-89 Page 1 

Copyright Apple Computer, Inc. 1984-1989 

Loc F Object Code Addr MSource Statement 


¥ void pascal_string_copy(char* src, char* dest); 


00000 




strcpy 

proc 

export 

00000 

4CD7 

0300 



movem.1 

(SP),A0-A1 

00004 

7000 




moveq 

#0, DO 

00006 

1011 




move.b 

(Al),DO 

00008 

6002 


ooooc 


bra. s 

@1 

0000A 

10D9 



@loop: 

move.b 

<A1)+, (A0) + 

0000C G 

51C8 

FFFC 

0000A 

01: 

dbra 

DO,@loop 

00010 





endproc 







end 



Elapsed time: 0.08 seconds. 

Assembly complete - no errors found. 16 lines. 


The opcodes we need are tantalizingly close, but embedded in material that we need to 
strip away. The first job is to extract the inline’s declaration and copy it to the output 
Hex constants must be separated by commas—we accomplish this with a variable, initially 
empty, that is set to a comma-and-space when a hex constant is emitted, so that a comma 
precedes every hex constant but the first one. 

/;¥[ dt]*([-«;]*)®1/ 

Print -n ®1 " =3n{" 

Set PRECEEDING__COMMA "" 

Delete 

The regular expression matches the inline declaration in the comment (which can be 
recognized by virtue of the marker string, that we put there). The text of the inline is 
extracted, omitting a possible trailing semicolon, and put into the variable ®1. The Print 
statement emits the inline declaration (in ®1) and extra stuff needed for C inline syntax. 
The PRECEEDING_COMMA variable is set to empty, the line is deleted, and processing 
continues. 

The inline declaration is terminated by an ENDP or an ENDPROC assembler directive: 

/[ 3t]ENDP/ 

Print " };dn" 

Delete 

Next, totally uninteresting lines are deleted. Examining the assembly listing, we note that 
the lines with the object code we need invariably contain a hex constant starting in the 
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first column, several spaces (with an optional “G”), and at least one two-byte hex constant. 
We'll strip every line that doesn't meet these criteria, so that there will be less noise to 
worry about. 

!/. [0 -9a-f]+ [ g] [0-9a-f]«4»/ 

Delete 

Then we simply delete any junk that precedes the hex constant we're interested in: 

1,$ Replace /[0-9a-f]+ [g ] / "" 

Now the line contains one word of assembler output that we can copy to the output: 

/• ([0-9a-f]«4»)®1 / 

Print -n PRECEEDING_COMMA "Ox"®l 
Set PRECEEDING_COMMA ", " 

Replace // "" 

We print an optional comma, followed by the hex constant itself. Then we arrange for 
future constants to be preceded by a comma, and remove the constant from the front of 
the line. 

Now we have a problem—there's no way to tell how many more constants have to be 
processed on the line under consideration. Furthermore, StreamEdit has no control 
structures for looping, so a count wouldn't help much anyway. We resort to an artifice, 
namely, repeating the above code as many times as we're likely to ever need it for a single 
line of assembler output. 

# 

# Convert remaining words on line 

# 

/•([0-9a-f]«4»)®l / 

Print -n ", Ox”®l 
Replace // 

/•<[0-9a-f]«4»)®l / 

Print -n ", Ox"®l 
Replace // "" 

/.<[0-9a-f]«4»)®l / 

Print -n ", Ox"®l 
Replace // "" 

/•([0-9a-f]«4»)®1 / 

Print -n ", Ox"®l 
Replace // 

Examination of the assembler output shows that handling five constants on a line is more 
than enough. However, if the assembler listing format changes, the script will break. 


Unpacking Unix Shell Archives 

This script unpacks a Unix shell archive, more commonly known as a sbar file. Shar files 
are used in the Unix community to gather text (say, the sources for a program, including 
its makefile) into a single file, suitable for transmittal by electronic mail or Usenet. 
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Shar files typically have the form: 


Files 

Limitations 

See Also 


garbage at the beginning — mail headers and so forth 
sed "s/ A X//" >TheFile «'END_OF_TheFile ' 

Xtext of the file 
X where each line 
X is preceded by an 'X' 

END_OF_TheFile 

more files, similarly packed 

The Unix shell and the tool sed cooperate to strip off the “X”s at the beginning of each 
line, and to direct the output to the correct file. Unfortunately the MPW Shell does not 
have this kind of redirection, and StreamEdit is not sed , so we have to come up with our 
own solution. 

To make matters worse, there is no single format for a shar file—in the Unix community 
it’s “anything goes,” as long as the standard Unix tools can unpack it. A StreamEdit script 
to unpack an arbitrary shar file would have to closely emulate the Unix environment, 
which is rather difficult. In practice, you will have to tweak this script to handle different 
kinds of shar files. 

The script starts with the usual MPW Shell commands to start up StreamEdit with the 
proper script, pass along the command-line parameters, and exit. 

; streamedit -d -s ‘which M {0}”‘ {parameters} 

; exit 


The variable FILE holds the name of the current output file. When we see a line beginning 
with “sed”, we extract the output filename (possibly enclosed in quotes) and put it in the 
variable. 


• Set FILE "DELETE.ME” # for safety's sake 

/•sed/ && ( />[ 3t]*3 , ([-i 9t]*)®l9* / # sed ... > • quotedFile' 

I I 

/>[ 9t]*([-i dt>]*)®l / # sed ... >notQuotedFile 

) 

Set FILE ®1 

print "Extracting " FILE 

For paranoia's sake, the FILE variable is initialized to “DELETE.ME”, and the name of each 
file extracted is printed on standard output. 

Extraction is simple—for every line beginning with an “X”, the “X” is stripped off and the 
line is written to the current destination file. 

/•x/ 

replace // 
print -to FILE 


{ShellDirectory }StrEd. = . tmp Temporary output file. 

Lines of more than 1,000 characters are silently split. 

There is no easy way to do a Replace operation on a variable. 

There are no “true” expressions — arithmetic is impossible. 

There are no conditionals or other control structures. 

Shell documentation on regular expressions. 
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MPW 

C Marker 

Syntax 

Description 

Type 

Input 

Output 

Diagnostics 

Status 

Options 
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— C++ / ANSI C Recognizer, Preprocessor and 
Marker Tool 

CMarker [option...] [file...] 

CMarker reads the specified C++ / ANSI C source file(s), syntax checks them and 
generates appropriate "Open” and "Mark" MPW commands, which, when executed, will 
mark the source file(s) at each function definition with the marker name being the name 
of the function. It’s purpose is to aid in the marking of source files for use with the 
MPW "marker browser" capability. CMarker contains a full ANSI C preprocessor and 
provides options to mark include files, generate source listings (with or without 
showing macro expansions), run the preprocessor only, flag anachronisms, and syntax 
check C++ / ANSI C with or without Apple extensions. 

Tool. 

If no filenames are specified, standard input is parsed. Each file specified on the com¬ 
mand line is parsed separately. 

"Open” and "Mark" commands are written to standard output for subsequent execution 
by the user. Additionally, if the -l[ist[ing]] option is specified, the source listing is 
written to standard output. Preprocessor output may optionally be written to the the 
file specified by the -ppout option. 

Errors, warnings, and anachronisms are written to diagnostic output. If the 
-plrogress] option is specified, progress and summary information is also written to 
diagnostic output. 

The following status codes may be returned: 

0 No errors. 

1 Parameter or option error. 

2 Execution error. 

3 Syntax errors. 

Options may appear in any order and may be interleaved with the file names. All 
options apply to the compilation of all the files. 

-a[nachronisms] Suppress anachronisms messages. By default, warnings 

for obsolescent ANSI C features and C++ anachronisms 
are written to diagnostic output. 

-d[efine] name[-string] Define name to the preprocessor with the value 1 if the 

[jiame[=string]]... string is omitted, or with the value of the string. This 

is the same as writing #defines for these names at the 
beginning of each source file. 
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-e 


■errors 


-extensions] aa, I off 


•i[ncludes] 

palhname[jpathmme \... 


-language] £.1 "C++" 


•linesize n 


Show macro expansion in the listing (-l[ist[ing]]) 
and/or preprocessor output files (-ppout). Note, this 
option is assumed if a preprocessor output file is 
specified (-ppout). 

Suppress marking if errors are detected. The default 
(i.e., not specifying -errors) is for CMarker to generate 
marker commands, regardless of syntax errors. 

CMarker can generate erroneous marker commands if the 
errors are sufficiently severe to confuse the parser; 
specifying -errors will cause CMarker to terminate 
before emitting marker commands. 

Control whether Apple extensions are supported. 
Extensions include the SANE data types, Pascal 
declarations, etc. By default, the extensions are 
supported (i.e., on is assumed). Setting the extensions 
off will result in the Apple extensions generating 
syntax errors. Note, with extensions on, the value of 
the macro_STDC_is set to 0. 

Search for include files in the specified directories. 
Multiple -i[ncludes] options may be specified. At 
most 14 directories are searched. The set of directories 
should be the same as that used for compilation in order 
to get all the preprocessor definitions. 

The search order is: 

1. The include filename is used as specified. If a full 
pathname is given, then no other searching is 
applied. If the file isn’t found, and the pathname 
used to specify the file is a partial pathname (no 
colons in the name or a leading colon), then the 
following directories are searched. 

2. The directory containing the current input file. 

3. The directories specified in -i[ncludes] options, in 
the order listed. 

4. The directories specified in the MPW Shell variable 
{CIncludes}. 


Specify the target sources as either C or C++. The 
default is C. If you specify C++ explicitly, it must be 
quoted in MPW. 

Specify the maximum number of characters generated in 
a single listing line before a newline is inserted to fold 
the line. The default, for all practical purposes is 
infinity, or more precisely, about 1024. 
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-l[ist[ing]] Generate a listing of the source to standard output. The 

listing includes line number information (total line and 
file line). If -showskipped is specified, lines which 
are skipped in the input due to conditionals are also 
shown and flagged accordingly. 

•mc68881 Define the macro name mc68881 as having the value 

1. This is the same as writing a #define for this name 
at the start of each source file. If this option is not 
specified, then the macro name me 6 8 8 81 remains 
undefined unless defined by the *d[efine] option above. 
This option is only provided for compatibility with 
MPW C because the macro it generated may be used in 
the source. 


-msi 


-PP 


ppout filename 


-p[r ogress] 


showskipped 


Generate made commands for include (header) files. 
Specifying this option will generate mark commands for 
methods (function elements) defined in header (".h”) files 
which are "#included" in the source. The default is to 
inhibit marking header files (Applicable to C++ files 
only). 

Preprocessing only. The syntax parser is turned off. 
Mark commands will not be generated. 

Write the preprocessor output to the specified filename. 
The preprocessor output is essentially the same as the 
listing output, but with all additional listing 
information removed. As such, it could be used as a 
source input file to a compiler. Note, specifying the 
•ppout option implies the -e option to show macro 
expansions. 

Write CMarker’s version, progress, and summary 
information to diagnostic output. 

Show lines skipped by conditional compilation in the 
listing output. 


-1 Display processing time and number of lines to 

diagnostic output even if progress information (- 
progress]) is not being displayed. 


u[ndefine] name[/iame ]... Undefine the predefined preprocessor symbol name. 

This is the same as writing #undef for the name at the 
beginning of each source file. This option is provided 
for compatibility with MPW C. The same names 
predefined in MPW C are predefined here, e.g., 

_FI le , L ine _, etc. See also the - 

mc68881 option above. 
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Limitations CMarker contains a parser that is only a C++/ ANSI C syntax recognizer. It is not a 



compiler and does not have any of the semantic constraints that can be detected by a 
compiler. Where MPW C and ANSI C differ, the grammar will only accept ANSI C. 
The preprocessor is also more fully ANSI C than MPW C (particularly in the way 
macros are handled). This means that sources containing certain "old-fashioned" C 
constructs will be flagged in error and in some cases confuse the parser enough to 
generate several errors. Generally, however, the markers will be generated correctly. 

In C++ and ANSI C there are many semantic constraints imposed on the syntax. These 
are nonexistent here. Therefore, C++ / ANSI C source which is syntactically correct 
and accepted by the parser has no guarantee of successful compilation. It should be 
remembered, however, that the intent of CMarker is not to provide a syntax checker 
(although it does a pretty good job of that), but to generate "Mark" commands for the 
MPW Marker Browser. 


Known Bugs CMarker will occasionally emit erroneous mark commands if the parser has detected 
errors of sufficient severity as to get confused. See the -errors option above. 
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Get — Retrieval and Indexing Tool for Large Text Files 


Syntax : 

Get (, dataFile ... I -dfl listFile) [-x] [-k key] [-col n] [-d default key] [-h I -h2] [-1] [-nf] [-q] 
[-s] [-search] [-t] [-sfl] [-y] [-field field list [-format format string ] ] 

[-lessFields field list] 

If Get is successful then the record in the data file associated with key is written to the 
standard output. If it is unsuccessful then the error message "### key NOT found" is 
written to standard error. 


Status: 


0 

1 

2 

3 

4 



Potions: 


no error, search was successful 
syntax error 
error in processing 
system or out of memory error 
key not found (-k key) 
user abort 


dataFile...: One or more specially formatted files, each of which must be 

accompanied by an index file whose name is of the form 
dataFile. index, and whose file type is btre. 

-dfl listFile: This is an alternative to the dataFile parameter. listFile 
specifies a file which contains a list of data file path names. 
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-k key: 


-width w: 


-d default: 


-h: 


-h2: 


A key word in the index file (. index) . A search is made for this 
key word; the search starts with the first listed data file and con¬ 
tinues through the datafiles in the order in which they are listed, 
either as the dataFile parameter or as the list in listFile. 
There is a side effect of the search in the special case that the key 
is the file name (the terminal name, not the full path) of one of the 
data files and the -df l listFile option is used. The side effect 
is that the file name used as a key will be moved to the top of the 
list in listFile. 

Display results in multi-column format to fit a display window 
whose width, in characters, is w. Must be a number between 1 
and 200. This option applies only to key lists, either specified 
explicitly by the tag $kl in the data, or implicitly by use of the -l 
or -search options. The option, when applied to other kinds of 
results, is ignored. 


If the key word parameter is null, use “default” as the key word. 
Example: get MPWHelp -k -• -d help will use “help” as the 
keyword, get MPWHelp -k Asm -d help will use “Asm” as 
the keyword. This is useful in scripts where a possibly omitted 
keyword is passed as a parameter. 

Output a header, e.g.: 


hd80:411:MPWHelp 

hd80 :411 :CIncludesHelp Look up... "FindWindow" 

hd80:411:InsideMacintoshHelp 

hd80:411:PInterfacesHelp 

hd80:411:ResourcesHelp 

hd80:411:TechNotesHelp 


«data for "FindWindow" goes here...» 

List all data files in the header. The “Look up” line appears 
opposite the file actually used. 

Similar to -h, but include in the header only the single data file 
that is actually used. 
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-m 

-I: 

-nf: 

-q: 

-s: 

-search: 

-t: 

-field 
Held list 

-format 

format 

string 


Select the key word that was found. (This must be used in 
conjunction with -h or -h2, which causes a display of the key¬ 
word in the form: Look up... keyword.) Assign a marker to the 
selection and set Saveonciose for the active window to False. 

List all keys that begin with the letters of the named (-k key) key 
word. If no key word is specified, then list all keys in the data 
file. Only the first listed data file is searched 

Example: The command get MPWHelp -k asm -l produces the 
list: 

Asm 

AsmCvtIIGS 

AsmllGS 

AsmMatlIGS 

No filtering. Return the key word's data exactly as 
it appears in the data file (including field tags). 

Quiet! Don't output ### key not found when a key is not 
found. 

Select the key word from the current selection in the active win¬ 
dow. For obvious reasons, this can only be used in a script acti¬ 
vated from a menu. 

Search the data file for all occurrences of key word (-k key) and 
return a list of all keys whose records contain that key word. 

Only the first listed data file is searched. 

Output only a template of the function or procedure requested. 

This option specifies which of the data fields, associated with a 
key word, to display. It is a comma-separated list of case sensi¬ 
tive field tags. 

Example: -field c,kl,t,fc 

This option may be used in combination with the -field option. 

It is used to specify string information that is to be put in front of 
the data associated with a given field tag. The string %s termi¬ 
nates the string information for a given tag and represents the data 
associated with that field tag. The set of %s symbols is in one-to- 
one correspondence with the set of field tags in the field list of the 
-field option. 
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Example: 

get cincludeshelp -k sin -field Fc,D produces as Output 

{CIncludes}Math.h 
extended sin(extended x); 

get cincludeshelp -k sin -field Fc,D 

-format "The file is: %sThe declaration is: %s” 
produces as output 

The file is: Math.h 

The declaration is: extended sin(extended x); 

- s f 1 Produces an ordered list of the requested data files. This is useful 

only in conjunction with the option -dfi listFile. 

- y The index file is automatically built if it is out of date or missing. 

This option causes it to happen silently, In the absence of the 
option, a dialog will be presented asking whether the index file 
should be built. 

-x Build, or if it is out of date, rebuild the cross reference index file 

for the named help file. 

Example: Get NewHelpFile -k <anyKey> -x will build or 
rebuild the cross reference index file NewHelpFile. windex. 
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ProcNames—display Pascal procedure and function names 

ProcNames has been enhanced to have the ability of generating MPW Shell mark commands to place 
markers on all the procedures and functions in a Pascal file. 

New and Modified Options : 


- b Display line number information for the the start of the 

procedure or function body (i.e., its BEGIN) instead of the 
header. If marker commands are being generated (-m), the 
markers will be placed on the procedure or function BEGIN 
that delimits its body. 

-cond Process Pascal $setc and $ifc, Selsec, $endc conditionals. 

This option is assumed if -d, -MC68020, or -MC68881 
options are specified. Pascal conditionals must be processed 
if you process USES statements (-u option) and those 
USES reference {PInterfaces}. Due to the way these 
interfaces are organized, ProcNames will not parse the Pascal 
source correctly unless the Pascal conditionals are processed. 
ProcNames will not list routine names which are skipped 
due to conditionals. 

-d name=TRUE I FALSE,... Set the compile time (Ssetc) variable name to TRUE or 

FALSE. This option has the same meaning and effect on 
compile time conditional as in the Pascal compiler. The 
purpose is to set initial value for variables tested by Pascal 
compile time conditionals statements ($ifc). The -cond 
option is assumed if -d is specified. 

Caution: the -d option is "overloaded"! If a Shell command 
line parameter of the form /uwne=TRUE I FALSE is 
specified, then this define form for the -d option is 
assumed. Otherwise the "reset to line 1 for each now file" 
form is assumed. For obvious reasons, a filename of the 
form id=id must not be placed immediately after a -d option. 

-1 n Process procedures and functions only to maximum nesting 

level n. 
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-m 


-MC68020 


•MC68881 


-o 


Generate MPW Shell marker commands instead of a display 
of procedure names. The marker strings will be the 
corresponding procedure or function names indented as a 
function of their nesting level. For units, marker commands 
will also be generated for the INTERFACE procedure and 
function declarations. The markers may be placed on the 
procedure header names (by default) or the BEGIN statement 
of the procedure’s body (using the -b option). You may 
want to use the -1 option to limit the markers to only the n- 
most outer procedures. 

Specify this option if the source has any Pascal directive 
conditional of the form {$ifc OPTION(MC68020)} and you 
use that fact to generate MC68020 code from the Pascal 
compiler. The -cond option is implied by using this 
option. 

Specify this option if the source has any Pascal directive 
conditional of the form {$ifc OPTION(MC68881)} and you 
use that fact to generate MC68881 code from the Pascal 
compiler. The -cond option is implied by using this 
option. 

The source file is an Object Pascal Program. The identifier 
OBJECT is considered as a reserved word so that Object 
Pascal declarations may be processed. The default assumes 
that the source is not an Object Pascal program. If markers 
are being generated (-m), then marker commands will be 
generated to mark the names of all objects declared in the 
input file. 


Limitations changes/additions : 

The limitation that recommends against using the -u option to request processing of USES declarations is 
no longer applicable. The following paragraph should be added to “limitations”: 

When Pascal compile time conditionals are processed, the form {$ifc 0PI10N(id)) is only 
fully supported when the id is MC68020 or MC68881. In all other case this form of $ifc 
evaluates to TRUE. The Pascal SMC68020 and $MC68881 are treated as special cases 
and tracked by ProcNames. The only reason for this is to handle the {$ifc OPTION(id)} 
conditional. It is unreasonable and impracticable to have this ProcNames track every 
Pascal compiler option that exists or may exist in the future. MC68020 and MC68881 
have been singled out since they, of all the Pascal options, are the most likely candidates 
to be used generally in Pascal source. Most other options are very specific to the Pascal 
compiler itself and are unlikely to be used. Indeed, the SMC68881 is explicitly tested in 
SANE.p. Currently there are no other uses of the {$ifc OPTION(id)} form in any other 
of the standard Pascal libraries. 
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MPW 3.2 Appendix E 
Release Notes 


PasRef—Pascal cross-referencer 

New options have been provided for this tool, and changes have been made to the “Limitations” section as 
given in MPW 3.0 Reference, Vol.2. 

New options : 


-cond 

Process Pascal Ssetc and $ifc, Selsec, $endc conditionals. 

This option is assumed if -d, -MC68020, or -MC68881 
options are specified. Pascal conditionals must be processed 
if you process USES statements (-u option) and those 

USES reference {PInterfaces}. Due to the way these 
interfaces are organized, PasRef will not parse the Pascal 
source correctly unless the Pascal conditionals are processed. 
PasRef will not list in the cross-reference identifiers in 
statements which are skipped due to conditionals. In the 
generated source listings, conditionally skipped lines are 
flagged with a "*". 

-d name =TRUE 1 FALSE,... 

Set the compile time (Ssetc) variable name to TRUE or 

FALSE. This option has the same meaning and effect on 
compile time conditionals as in the Pascal compiler. The 
purpose is to set initial values for variables tested by Pascal 
compile-time conditional statements ($ifc). The -cond 
option is assumed if -d is specified. 

Caution: the -d option is "overloaded"! If a Shell command 
line parameter of the form name =TRUE 1 FALSE is 
specified, then this define form for the -d option is assumed. 
Otherwise the "reset to line 1 for each now file" form is 
assumed. For obvious reasons, a filename of the form id=id 
must not be placed immediately after a -d option. 

-MC68020 

Specify this option if the source has any Pascal directive 
conditional of the form {$ifc OPTION(MC68020)) and you 
use that fact to generate MC68020 code from the Pascal 
compiler. The -cond option is implied by using this 
option. 

-MC68881 

Specify this option if the source has any Pascal directive 
conditional of the form {$ifc OPTION(MC68881)} and you 
use that fact to generate MC68881 code from the Pascal 
compiler. The -cond option is implied by using this 
option. 
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Limitations changes/additions : 


In the limitation that specifies the number of symbols Pasref can handle, the number has been changed from 
5000 to 6000. 

The limitation that recommends always using the -nu option to suppress processing of USES declarations 
is no longer applicable. The following paragraph should be added to “limitations”: 

When Pascal compile time conditionals are processed, the form {$ifc OPTION(id)) is only 
fully supported when the id is MC68020 or MC68881. In all other case this form of $ifc 
evaluates to TRUE. The Pascal SMC68020 and SMC68881 are treated as special cases 
and tracked by ProcNames. The only reason for this is to handle the {$ifc OPTION(id)} 
conditional. It is unreasonable and impracticable to have this ProcNames track every 
Pascal compiler option that exists or may exist in the future. MC68020 and MC68881 
have been singled out since they, of all the Pascal options, are the most likely candidates 
to be used generally in Pascal source. Most other options are very specific to the Pascal 
compiler itself and are unlikely to be used. Indeed, the SMC68881 is explicitly tested in 
SANE.p. Currently there are no other uses of the {$ifc OPTION(id)} form in any other 
of the standard Pascal libraries. 
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MPW 3.2 Appendix F 
Release Notes 


FileDiv—divide a file into several smaller files 

The functionality of FileDiv has been expanded. FileDiv now allows an input file to be viewed as 
containing an arbitrary byte stream in its data fork. The first paragraph of “Description” (MPW 3.0 
Reference, Vol. 2) should be amended to read: 

FileDiv is the inverse of the Concatenate command. It is used to break a large 
file into several smaller pieces. The input file is divided into smaller files, each 
containing an equal number of bytes or lines determined by the splitpoint 
(default=2000 lines or 10000 bytes). The last file contains whatever is left 
over. The file to be read can either be viewed as a sequence of TEXT file lines 
(the default), or as an arbitrary typed file with a byte stream in its data fork 
(using the -b option). 


The following options have been changed : 


-f _add the following sentence: 

The -f option is ignored if the -b option is specified. 

-n splitpoint Depending on whether or not the -b option is specified, 

split the input file into, respectively, groups of splitpoint 
bytes or splitpoint lines. (Note that for the case of lines, the 
-f option causes splitting into groups of splitpoint or more 
lines.) 

The following options have been added : 


- b The input file is viewed as an arbitrary typed file with a byte 

stream in its data fork. This file is divided into groups of 
bytes with each group containing up to the number of bytes 
specified by the splitpoint. If this option is omitted, the file 
is assumed to be a TEXT file composed of a sequence of 
lines. 

-s N When the -b option is used, the input/output byte streams 

are buffered in buffers whose size are N*512 bytes. The 
default value for N is 128 (yielding 65536 byte buffers). Use 
this option to change N. Values 1 to 512 are allowed. 
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MPW 3.2 Appendix G 
Release Notes 


PROJECTOR 

An Informal Tutorial 


Introduction 

Projector is an integrated set of tools and scripts whose primary purpose is the control of source code. 
The system has two basic functions. The first is to make it practical to have several people working simul¬ 
taneously on a project By allowing only one person at a time to modify any given file, it prevents a 
programmer from inadvertently destroying changes made by another. The second function is to preserve, in 
an orderly manner, revisions of a file and commentary on the revisions. This enables programmers to find 
out the author and revision date, to read the revision commentary, and if desired, to retrieve the revision 
itself. 

Projector represents a considerable advance over older systems, such as SCCS and its descendants, 
known to users of UNIX®. It uses its own window interface for three of its commands (NewProject, 
Checkin, and Checkout). These windows, unlike Commando windows, can stay open indefinitely. The 
Commando interface is also available for all commands, although its use is not recommended for the three 
commands just mentioned. Projector also differs from SCCS in that its use is not restricted to text files. 
However, the data compression achieved by storing only one complete copy of a file and storing revisions 
as files of differences is only available for text files. Projector also has a degree of flexibility which permits 
different users of the same set of files to view them differently. This is accomplished by giving each user 
independent control of the mapping between the local directory hierarchy into which he/she keeps the files 
and the hierarchy used for their storage in the Projector database. Finally, Projector has a facility for associ¬ 
ating a specific set of file revisions with a name, this name being usable as a designator for a particular 
version, or release, of a product. Thus, the name alone can be used to trigger the selection of just those 
sources that are required to build the desired instance of the product. 

This tutorial begins with a section that discusses the basic concepts and terminology. Following this 
are sections that demonstrate the use of Projector by creating a database skeleton from scratch, putting files 
into it, and performing various revision activities. These sections are illustrated with screen shots taken 
during the actual operations. 


Concepts and Terms 

The top level, fundamental construct in a Projector database is called a project. Projects are analogous 
to directories in an HFS (hierarchical file system). A project may contain files and may contain other 
projects; just as a directory may have sub-directories, a project may have subprojects. The difference is that 
a file name in a project represents all revisions of the file—this is known as a revision tree —and is also a 
pointer to file information and revision information. File information is descriptive text that applies to all 
revisions, while revision information is descriptive text that relates to a single revision. Fig. 1 illustrates 
the project hierarchy that will be used throughout the next chapter. 
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The symbol “/” is used as a separator in naming projects much as the symbol is used in hierarchi¬ 
cal file names. Thus, Base/ is a project, Base/SourcesJ is a subproject of Base/, and Base/Sources/Cj is a 
subproject of Base/SourcesJ. As is the case with directories, the terminal separator may be omitted, e.g. 
Base/Sources. Although there is a parallel concept to that of current directory, namely current project, there 
is no provision for a partial project name relative to the current project. That is, if the current project is 
Base/, Base/Sources cannot be denoted by /Sources/. 

When a project is created, what one actually creates is a directory whose name is the project name. 

This directory always contains two files, one called_ CurUserName that is invisible to the finder but 

shows up in some dialogue windows, and one called ProjectorDB that contains all of the project data. If the 
project has subprojects, then this directory will contain subdirectories (folders) that similarly house the 
subprojects. That is, a subproject folder will be named after the subproject, and will contain its own 
ProjectorDB file for the subproject data. 

The act of checking out a Hie to a given directory is merely that of “copying” the file from the Projec¬ 
tor Database to the directory in question. “Copying” is in quotes because in actuality the projector software 
may be synthesizing the file dynamically from a set of differential revision data. A checked out file 
contains a resource named ckid which identifies it as a file produced by Projector. This resource contains, 
amount other things, the file’s revision number, whether or not the file is write-protected, and the text of 
the revision information. 

Files may be checked out as read-only or as modifiable. If the Projector Database is accessible to 
multiple users, e.g. on a server, then many users may simultaneously check a file out, but only one user at 
a time may check it out as modifiable. 

A file which has been checked out as modifiable may be checked in after modification. This enters the 
modified text as a new revision of that file in the Projector Database. 

A checkout directory is a directory that has been associated with a project (or subproject) by execu¬ 
tion of the command CheckOutDir. This association is private to the user and vanishes when the current 
MPW session ends. It may also be modified during an MPW session. The association defines the directory 
into which the files of the project will be checked out by default There are no restrictions on this associa¬ 
tion. The seven projects shown in Fig. 1 may be checked out to seven different directories that bear no 
relationship to each other, may all be checked out to one directory, or (most commonly) may be checked 
out respectively to a directory structure that matches that of the project hierarchy. 

A name is an identifier that can be attached to a group of specific file revisions, but only to one revi¬ 
sion for any given file. It is used in commands as an pseudonym for this group, most commonly for rapid 
selection of the revisions belonging to a particular release. Names may be private or public. Public names 
become project attributes and are automatically available to all users. Private names are available only to 
the user who defines them, and last only for the duration of the MPW session. 
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Base/ 



Fig. 1 


Project Creation 

Let us construct the project hierarchy of Fig. 1. Under the menu item “Project” in the MPW menu 
bar we can select the item “New Project.” The “Project Menu” is illustrated in Fig. 2. 


6 File Edit Find Mark tllindow 

Project 

| Help Build 

.... HD:MPUJ:lllorksheet HH 

meek in... 

Check Out... 

New Project... 
Mount Project... 

Set Project... 

Compare Active... 
Merge Active... 


Fig. 2 


We obtain a special Projector window. It is a bit like a Commando window, but it stays open until 
one clicks on the “close” box and it can be moved about on the screen. On the left side is a typical file 
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selection sub-window. We wish to establish this project inside of an already-existing directory called 
“ProjectDemo,” and therefore navigate in the standard way until this directory is selected, giving the window 
as illustrated in Fig. 3. You can see it already contains two directories. Documents and Examples, which 
have nothing to do with the proposed project. The user enters the name “Base” and the comment respec¬ 
tively into the boxes labelled “Project Name” and “New Project comment.” The User field is automatically 
set to the value of the MPW variable “user.” 


Nem Project 


SC 


€3 ProjectDemo | 


O Documents 
CD Examples 


(Open 


O 


Driue ] [ Eject 


Project Name: 


Base 


User: Herb Kanner 
Nem Project comment: 


Base is a demonstration project. It will 
contain subprojects Sources and Interfaces, 
and will also contain files BuildScript and 
MakeFiIe. 


o 


| Nem Project^) 


Fig. 3 

After pressing the “New Project” button, the window looks like Fig. 4. The directory containing the 
empty database for the project Base has been created; its name can be seen in the left-hand window. 

Now, clicking on the item “Base” in the left-hand sub-window will activate the “Open” button. 
Clicking on the latter or double-clicking on “Base” will make it the current directory, and now the new 
projects “Sources” and “Interfaces” can be created as subprojects of “Base” in the same way as “Base” was 
created. Fig. 5 shows the window after this has been done. The Projector files belonging to “Base,” 

namely “_CurUserName” and “ProjectorDB” are visible but dimmed. Similarly, the two subprojects “C” 

and “CPlus”that are subprojects of both Interfaces and Sources can be created. Fig. 6 is the Finder window 
for Base, showing the folders (directories) for the subprojects Source and Interfaces and the actual Projector 
file for Base: ProjectorDB. Fig. 7 contains the Finder windows for both Sources and Interfaces, showing 
their ProjectorDB files and their subprojects. 
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Neui Project 


e=.SC 

€5) ProjectDemo | 


CD Documents 
CD Examples 


[Open) 

[ Driue ] [ Ejecl ~) 


Project Name: 


User: Herb Kanner 
Netu Project comment: 


Base is a demonstration project. It will 
contain subprojects Sources and Interfaces, 
and will also contain files BuiIdScript and 
MakeFile. 




Fig. 4 


Neui Project 


oSC 
€3 Base | 


CD Interfaces 
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Fig. 5 


MPW 3.2 Appendix G 
Release Notes 


5 


Copyright Apple Computer, Inc. 
1990-1990. All rights reserved. 




































































All files and revisions 
are contained in this ^ 
HFS file. 


3 items 34,313K in disk 44,424K evail 

Cj O' 

Sources ^ Werfaces 
* 

* 

* 

* 

n 

jectoi 

rDB 

£ 

Ijljlj 

<> 

0 0 



Fig. 6 


Sources 


3 Hems 


18/793K in disk 166K available 


o o 


ProjectorDB C CPlus 


!□! 


Interfaces 


3 Hems 18 ,793K in disk 166K available 


o n 


ProjectorDB C CPlus 


K 




a 


Fig. 7 


Before proceeding to the use of Projector for the storage, updating, and retrieval of files, it is necessary 
to discuss the commands MountProject and Project. What we have done so far is to create a skeletal 
Projector database, that is a hierarchical project structure and implicitly to mount all of the projects. 
Mounting a project is analogous to opening a file. It makes the MPW Shell aware of the project and 
makes the project data available to the user. Prior to mounting, projects exist only in file storage media. 
The next time MPW is initiated, the projects whose creation was illustrated in Figs. 1-4 will have to be 
mounted again before they can be accessed. The simplest way to do this is with an unadorned MountProject 
command whose parameter is the project’s directory: 

MountProject SC:ProjectDemo:Base 

Mounting a project automatically mounts all of its subprojects, so only this one command is required. One 
can also use Commando, and in fact the Commando window for MountProject can be activated directly 
from the “Project” item in the MPW menu bar. The radio button should be left at its default value 
“Generate MountProject Commands.” When the button labelled “Project Location” is pushed, the choice 
“Select a project to be mounted...” will cause generation of the normal dialogue window for directory selec¬ 
tion. The one selected will become the argument for the MountProject command. 
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A related command that is worth introducing at this point is Project. Analogous to the file system 
concept “current directory” is the Projector concept “current project” The Project command is used to set 
the current project, and, again in analogy to the behavior of Directory, when given with no parameters it 
returns the value of the current project A special Projector window is available from the menu bar, called 
“Set Project....” It displays all mounted projects in project hierarchy notation (using 1); the selected one 
will become the current project. 

The MountProject command can also be given with no parameters. In that event, it returns the names 
of all currently mounted “root level” projects. The default behavior when doing this is to return each name 
in the form of a complete MountProject command, i.e., to precede the project name with the word 
MountProject. Figs. 8-10 illustrate some uses and variants of the Project and MountProject commands. 


HD:MPUJ:Lliork$heet 


MPV Shell 


#The Project command vilh no parameters returns the current project: 
project 

Base/S ounces JCJ 


#Novsetthe project to Base: 
project Base 

# and confirm that it got set: 




project 

Base; 


# MountProject vith no arguments returns aMountProject command that 

# v*ll mount the current project, handyforfuture use. The returned 

# parameters anHFS path to the directory containing the project: 

mount project 

MountProject SC:ProjectDemo:Base: 


liijjijl 


t The -r option causes commands to be generated recursively for 
# the full project hierarchy 

mountproject-r 

MountProject SC:ProjectDemo:Base: 

MountProject SC :ProjectDemo: Base Interfaces: 

MountProject SC:ProjectDemo:Basejnterfaces:C: 
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MountProject SC:ProjectDemo:Base:Sources: 

MountProject SC:ProjectDemo:Base:Sources:C: 

MountProject SC:ProjectDemo:Base:Sources:CPIus: 
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Fig. 8 
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#The-pp option causes the commands to be Project and the paths to be 
# project paths: 

mountproject-r-pp 
Project Base/ 

Project Basejlnt erf aces/ 

Project Base/Interfaces/C/ 

Project Basejlnt effaces/CPIus/ 

Project Base/Sources/ 

Project Base/S ounces /C/ 

Project Base/Sounces/CPIus/ 
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# Finally, t he -a option sup presses the commands: 
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SC: Proj ectD em o: Bas e: 

SC: Proj ectD em o: Bas e :lnt erf ac es: 

SC: Proj ectD em o: Bas e :lnt erf ac es :C: 

SC: Proj ectD em o: Bas e :lnt erf ac es :C PI us: 
SC:ProjectDemo:Base:Sources: 
SC:ProjectDemo:Base:Sounces:C: 
SC:ProjectDemo:Base:Sources:CPIus: 




Fig. 9 
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# after quitting end restarting MPW: 
mountproject SC:ProjectDemo:Base 

#Novconfirm that the entire hierarchy has been mounted: 

mount proj ect-r-s-pp 
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Fig. 10 
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This might be a good moment for the user to experiment with the “Mount Project” and ’’Set Project” 
items in the Project Menu. Mount Project is a conventional Commando window. Set Project creates a 
window (Fig. 11) that lists, for selection, all mounted projects. It is used in much the same way as the 
pop-up list of directories in the MPW Directory Menu. 


Select a neur current project: 

Base/InterfacesJ 

BaseJInterfaces/CPIusJ 

Base/ 


Base/Interfaces/CJ 


Base/Sources/CPIus/ 

Base/$ources/C/ 

Base/Sources/ 



Fig. 11 


Relating Directories to Projects 

Now that a tree of projects has been created, we wish to put some files into them. Let us make a 
simplifying assumption which corresponds to the most probably desired organization: that the directory 
structure into which the working copies of files are to go should be an exact replica of the project structure 
just created. The first step is to create the directory structure that will in time house the files when they 
have been checked out of a project. This is done with a command called CheckOutDir. In its simplest 
form it takes two parameters, a project and a directory. The effect of executing this command is a bit 
modal: it sets a default so that subsequent Checkout commands addressed to that project copy the files to 
the named directory unless another directory is explicitly named in the Checkout command itself. A side 
effect of CheckOutDir is that if the directory does not exist, it creates it. A lovely option to this command 
is -r; with this option, sub-directories are created corresponding to all subprojects and they are given the 
same names as the subprojects. As is the case with MountProject, a CheckOutDir command with no 
arguments creates an instance of the command showing the directory that corresponds to the current project 

For the purposes of this tutorial, we want to create a set of checkout directories that parallels the 
project Base. We would like to put them in the same directory that contains Base, namely :ProjecDemo. 
Since the name “Base” has been already used, we will call the root of the checkout tree “Baseckout.” 
Fig. 12 illustrates the use of the recursive CheckOutDir command. 
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CheckO utDir-r-project Base/ SC:ProjectDemo:Baseckout 

# Use the command vith no arguments to confirm the checkout: 

Ch eckO utDir-r 

CheckOutDir-project Base/ SC:ProjectDemo:Baseckout: 

CheckOutDir-project Base)lnterfaces/SC:ProjectDemo:Ba 3 eckout:lnterfaces: 

CheckOutDir-project Base/ 1 nteitacesjC/SC:ProjectDemo:Baseckout:lnterfaces:C: 

CheckOutDir-project Base/Interfaces/CPIus/ SC:ProjectDemo:Baseckout:lnterfaces:CPIus: 
CheckOutDir-project Base/Sounces/ SCiProj ectD emoiBas eck out: Sources: 

CheckOutDir-project Base/S ounces jC/ SC:Proj ectD emo: Bas eckout:Sources:C: 

CheckOutDir-project Base/Sources/CPIus/SC:ProjectDemo:Baseckout:Sources:CPIus: 

# Note that CheckOutDir will create the needed directories, if they do not 

# already exist. 

5 

ill III 

jjijj: 

jiirj: 

iiirir 

::•{:{ 

iiiiii 

Ijljlj 

Ijlili 

<> 


Pi 


Fig. 12 


Checking Files In and Out 

The most used and most complicated windows specific to Projector are Check In and Check Out. 
Check In moves file data from normal file storage into the Projector database. Check Out copies files from 
the database to normal file storage. The MPW commands Checkin and Checkout serve the same purpose, 
but other than for usage inside of scripts, it is strongly recommended that the windows, selectable by 
choosing respectively “Check In...” and “Check Out...” in the Project item of the MPW menu bar, be used. 
These windows remain open until explicitly closed, and can be moved to where desired on the screen. The 
two windows are partially keyed to each other in that changing the current project on either one affects both 
windows. Most of the illustrations in this section show both windows, although in practice usually only 
one is opened at a time. The examples reflect the directory/project structure created in die previous chapter. 

Let us now assume that the required files have been written in the appropriate directories, as shown in 
the following list:— 

:Baseckout 

Makefile 
BuildS cript 

:Baseckout:Sources:C: 

CSourceLc 

CSource2.c 

CSource3.c 

:Baseckout Sources:CPlus: 

CPlusSourceLc 

CPlusSource2.c 

:BaseckoutInterfaces:C: 

CInterfaces.h 
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:Baseckout:Interfaces:CPlus: 

CPlusInterfaces.h 


Opening the Check In and Check Out windows, we get the display shown in Fig. 13. 


CD SC 


Check In 
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Revision. 
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Selet t all J [ Open 


Selet t newer ) 
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User: Herb Kanner 
Task: 


Check Out comment: 


Select Files in Name: El Touch mod date 


None 


|<S> Read-only j 
jO Modifiable j 

□ Brant h I 


( Cant el l heckout ) 


— 


9 

• 

[(Check Out ]| 


Fig. 13 


At the upper right in the Check In window can be seen a button labelled “Project:”. The text on the 
button is the name of the current project. If no project has been mounted, this text will read “Root level 
projects.” The current project in this case is Base. If the button is pressed, the names of all projects pop 
up in a selectable list, with the subproject nesting indicated by levels of indentation. On the left is a 
display similar to the familiar dialogue used for opening files. Until a CheckOutDir command has been 
given, it merely displays the contents of the current directory. If the project shown in the “Project:” button 
has a checkout directory, then that directory will automatically be the subject of the display on the left. The 
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user may navigate freely within this left-hand portion of the window and select any directory and file on any 
mounted volume; we will return to the application of this later. On closing and re-opening the Check In 
window, or even by just leaving and project Base and then returning to it by use of the button at the upper 
right, the left-hand display will again be set to the checkout directory for Base. 

Note that the Check Out and Check In windows track each other in that they both always show the 
same current project. The left hand display of the Check Out window permits navigation through the 
project hierarchy and selection of files belonging to the Projector database in exactly the same manner as the 
customary dialogs for Open do for directories and files. Whatever project is selected as the current project 
also shows up on the Project button in the Check In window and vice versa. Whatever directory appears 
automatically near the upper left of the Check In window (right under the name of the volume) will also 
appear on the button labelled “Checkout to:” at the upper right of the Check Out window. The directory 
can be changed independendy in either of these windows. It automatically reverts to the one established by 
the CheckOutDir command (if such a one exists) on deselecting and reselecting the project. 

Now, let us redirect our attention to the Check In window of Fig. 13. We see in the left-hand display two 
subdirectories of Baseckout: Interfaces and Sources. No file names are visible even though the files 
BuildScript and MakeFile reside in the directory Baseckout. The reason is that the Check In window by 
default only lists files belonging to the current project Since the project “Base” is brand new, it does not 
yet contain any files. To make the file names Interfaces and Sources visible in the window, we mark the 
box labelled “Show all files,” yielding the window shown in Fig. 14. 
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The next step, of course, is to check these files in. Selecting a file and pushing the Check In button 
will enter the file and all ancillary information about it into the Projector database; this includes any Check 
In comment that has been written. After this has been done for both BuildScript and MakeFile, the 
windows will have the appearance of Fig. 15. This illustration also shows the Project pop-up list in the 
Check In window. 

Observe the icons used in both of these windows for files, directories, and projects. For a detailed list 
of the meanings of all of the Projector icons, see the MPW Reference Manual. Because the radio buttons in 
the Check In window were left at their default setting (Keep read-only), the names of the two files are now 
gray, indicating that because they were checked in, and because the copies in the directory Baseckout are 
now read-only, they clearly should not be checked in again. The icon indicates that they are read-only, and 
if one now opens die copy of the file in the checkout directory, one will see that same icon in the upper 
left-hand comer of the file window, and indeed, any attempt to write to that file will meet with failure. 

Notice that each window has a button labelled with a great big question mark. Pushing this button 
changes the right side of the window to an information window and modifies some of the other buttons. 
Doing this to both windows yields the pair shown in Fig. 16. Note that the window tides have been 
changed to remind one that they are now yielding informadon. The same button, now labelled “Done,” 
when pushed again causes the window to revert to its original state. 

Selecting and “opening” a file in the Check Out or Check Out/Information window demonstrates the 
next level of access, that of the file revision. Fig. 17 shows the appearance of the Information windows 
after opening MakeFile. We see an icon labelled “1,” the revision number of the only existing revision. 
As the file is checked out for modification and checked back in, additional such icons will appear, corre¬ 
sponding to all existing revisions. This permits easy fetching of earlier revisions when desired. The radio 
buttons labelled “Latest Revision Info” and “File Info” permit respectively the choice of a comment that 
applies to the specific revision selected and a comment that applies in common to all revisions of the file. 
The term “latest” in the label is not exactly accurate. It reflects the fact that the default selection will, in 
fact, be the latest revision. 

At the start of this section, it was assumed that the original revisions of the files to be checked in 
already exist in their correct checkout directories. This assumption was made for convenience. By first 
setting the desired project in the box at the upper right in the Check In window, checking the “Show all 
files” box, and then selecting desired files for that project by use of the left-hand sub-window, it is easy to 
check in files from anywhere . 
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When File Selected Show: 

(S) Latest Reuision Info Q File Info 


Name: MakeFile Reu: 1 

Author: Herb Kanner 

Checked In: Fri, Dec 1, 1989, 12:22 PM 


Task: 


Reuision’s comment: 


This is the initial reuision of MakeFile. 


o 


Reuert Saue 


Fig. 17 


Let us next assume that original revisions of all the files shown in Fig. 1 have been checked into their 
proper projects. It is now our intent to make some constructive changes to the file CSourcel.c. We go to 
the Check Out window, navigate in the left-hand area until the current project is BaseJSources/CJ, and select 
the file CSourcel.c. Before pushing the Check Out button, we make sure that the radio button 
“Modifiable” has been pushed. After writing a comment and pushing the Check Out button, we find that 
the two windows have the appearance of Fig. 18. Note the icon next to CSourcel.c in both windows; it 
indicates that the checked out copy is modifiable. If we now go to the Check Out/information window by 
pushing the big question mark and open CSourcel.c, we get the display of Fig. 19. We see that the 
revision being modified is called “1+.” After it has been checked back in, this number will change to 2. 

This last demonstration could also have been accomplished using the Check Out window, instead of 
using the Check Out/Information window. However, the file CSourcel.c appears dimmed in that window. 
This is correct. Because it has been checked out for modification, any other attempt at checkout must be 
only as a branch. Making the file unselectable cautions the user. This precaution can be overridden by 
holding down the option key while clicking on the file name. The file can then be opened to display the 
revisions as before. Notice that when an “open” is forced on a file that has already been checked out for 
modification, the box labelled “Branch” in the Check Out window is automatically marked. 
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Fig. 19 


Branching 

The normal sequence of checking out a file as modifiable, editing it, and checking it back in produces 
what is called “the main trunk,” a series of revisions that are numbered in sequence: 1, 2, 3,... . The 
button labelled “Revision...” in the Check In window may be used to create gaps in this sequence. That is, 
if revisions 1 through 4 exist, so that revision 5 would be created next, the use of this button makes it 
possible to name the next revision with an integer greater than 5. Often, it is desirable to pursue a parallel 
development while work on the main trunk proceeds. The revisions belonging to the parallel development 
are said to be on a branch. Methods will be shown later for merging files developed along a branch back 
into the main trunk. The notion of branching is recursive; a branch may be created that diverges from an 
already existing branch and this may be done to any desired depth. Multiple branches may be taken from 
the same revision. There is a numbering scheme for branch revisions which enables the user to visualize 
the tree, knowing only the revision numbers. This branching capability accounts for the term revision tree 
to describe the set of revisions of a file. 

Branching from the latest revision is simple. If, for example, the current revision of CSourcelx is 
Revision 3, then all that is needed is to click on the Branch box before checking out the file as modifiable. 
The file while it is checked out will be labelled Revision 3a+, and on being checked back in will become 
revision 3al. A second parallel branch from the main trunk would be labelled 3bl after check in. If 3al is 
checked out modifiable, revised, and checked back in, it becomes 3a2. A branch from 3a2 would become, 
after checkin, 3a2al, and so on. 

Branching from earlier revisions is slighdy more complicated. Let us assume again that CSourcel.c 
is up to Revision 3, and that it is desired to revert to Revision 1 and branch from there. Go to the Check 
Out window, press the “Modifiable” radio button, then select and open CSourcel.c. The three revisions 
will now show, but all but the last will be dimmed. Select Revision 1 by holding down the option key 
while clicking on it. Notice that the Branch box will be checked automatically. An alternative procedure is 
to select Revision 1 after pushing the “Read-only” radio button, and then pushing the “Modifiable” button. 
After checkout, the window will taken on the appearance of Fig. 20. After the branch is checked back in, 
the window will be as shown in Fig. 21. 
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Fig. 22 shows the members of a moderately bushy revision tree (the one hidden item is Revision 1), 
and Fig. 23 shows the same tree graphically. 
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We are now in a position to discuss most of the remaining features of the Check In, Check Out, and 
New Project windows. 

The boxes labelled “Touch mod date” to be found in both the Check In and Check Out windows cause 
the date of latest modification in the file system directory to be set, respectively, to the time of the checkin 
or checkout. By default, this is marked in the Check Out window and not in the Check In window. 
Although this can cause unnecessary revisions of this date, it guarantees an update on every checkout, 
meaning that tools like Make will always assume that they are being presented with a new version. If this 
default is not used, and more than one person is working on a file, then there is a danger that a user may 
check out a revised file and send it to Make without the latter program realizing that the file has been 
updated. If there is only one user working with a set of projects, reversing this convention and touching the 
mod date on checkin may be more convenient. 

The button labelled “Cancel checkout” is active when a file that has been checked out for modification 
is selected. Pushing this button changes the status of the file to read-only and discards any changes that had 
been made to the file while it was modifiable. 

The button labelled “Select all” causes selection of the latest revision on the main trunk of all files in 
the current project. It does not perform a checkout, just a selection. The button labelled “Select newer” 
selects, with one exception, those files for which the newest main trunk revision is not already to be found 
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in the user’s checkout directory. The exception is any revision which is on a branch. The assumption is 
that if a branch has been checked out, the user intends to keep it. This button does not distinguish between 
the main portion of a branch and sub-branches. A revision is either on the main trunk, i.e. its revision 
number contains no alphabetic characters, or it is on a branch, i.e. its revision number contains one or more 
alphabetics. If the option key is depressed while the “Select Newer” button is pressed, the selection action 
is modified so as not to select any revision whatsoever of a file unless a copy of the file already exists in 
the user’s checkout directory. This is equivalent to using a written Checkout command with the -update 
option. The idea is: select file revisions for checkout by the same criterion as “Select newer,” but do not 
check out revisions of any files that have not already been checked out. Just update the files that the user 
has checked out 

Multiple selection of a subset of the files shown in a Check In or Check Out window can be done in 
two ways. If the shift key is depressed while a second selection is made, then the previous selection is 
retained and all intervening names are selected, i.e., a contiguous set of names is selected. If disjoint set of 
names names are desired, then the command key should be depressed while making the selections after the 
first one. The “action” button of the Check In, Check Out, and New Project windows is keyboard activated 
by pressing the enter key. This is required because keystrokes, including that from the return key, are sent 
to the comment field in all three of these windows. 

Depressing the option key while pushing the Check Out button will cause automatic opening of the 
file being checked out if it is a text file. 

Some less frequently encountered icons are illustrated in the next two figures. Suppose that the user 
manually selects a directory in a Check In window that is not the “checkout directory” for the current 
project. For example, this might be done if the directory contains a file which is not yet a Projector file, 
and the user wants to check this file in to the current project. On marking the “Show all files” box, any 
Projector files in the directory which do not belong to the current project will be designated by an icon 
bearing a question mark and will have their names dimmed. This is illustrated in Fig. 24, where the current 
project is shown as C (actually BaseJSources/C) but the user has selected the directory BaseckouL Fig. 25 
illustrates one other icon that may be seen when multiple users have access to a Projector database. The 
user “joe” wishes to check out the file CInterfaces.h. The padlock icon indicates that this file has been 
checked out for modification by another user. Projector will only allow “joe” to check out the latest revi¬ 
sion as a read-only file. If “joe” wants to do any modification, he will have to create a branch. 
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Fig. 24 
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Finally, the Check Out/Information window has a facility for identifying the revision of a file that is 
currently checked out. The procedure is as follows: Obtain the Information window by pushing the button 
with the big question mark. In the left-hand area of the window, select and open the file in question thus 
showing its revision tree. Push the “Select mine” button. If any revision of that file exists in its checkout 
directory, that revision will be selected in the window, thus giving the desired information. 


Naming a Set of Revisions 

Facilities exist in Projector for associating a name with a chosen set of file revisions. Thus, for 
example, the revisions corresponding to a given release, say alpha 1, of a product can be given that name. 
As is illustrated in Fig. 26, the button in the Check Out window labelled “Select Files in Name:” will, 
when pushed, display a pop-up list of all known names. Dragging to the name “alphal” will then cause 
selection of that set of revisions, enabling easy checkout of the source files for that release. 
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Fig. 26 


The assigning of names is done with the command NameRevisions. Like several other commands 
already described, this command is used with parameters to associate a name with a set of revisions, and 
without any parameters to elicit information about existing name assignments. It is one of the more 
complicated commands in the lexicon. Fortunately, anything done with this command can be easily 
reversed with the command DeleteNames. 

The three most important options of the NameRevisions command are -public, -private, and 
•dynamic. The -public option, which is the default, establishes a name as public and relatively 
permanent It is recorded in the Projector database and will appear in the Check Out windows of all users. 
A private name exists only for the convenience of the user who defined it and lasts only for the duration of 
the current MPW session. The only way to give it any longevity is to have the command that created it 
saved in a script file. Private names appear first in the pop-up list and are separated from public names by a 
dotted line. 
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The option -dynamic is a little harder to explain. Let us consider a couple of scenarios that illustrate 
when this option is and is not wanted. First we will describe the simpler case, the one where the option is 
not used. Suppose that the latest revision on the main trunk of every file in a project is to be used for a 
release. The NameRevisions command written 

NameRevisions -project myproject -a thisrelease 


will freeze the name “thisrelease” to the latest main trunk revisions of files in the project “myproject.” The 
-a option indicates that we want all of the files in the project. The selection is static. That is, at some 
future time, by which many of the files may have been revised several times, the use of the name 
“thisrelease” will select that frozen set of revisions. The second scenario might be that one or more files in 
a project become obsolete. Suppose that a project has files validl, valid2, valid3, obsoletel, and obsolete2. 
It has been decided that obsoletel and obsolete2 will no longer be used. The command 

NameRevisions -project myproject -dynamic 9 
active validl valid2 valid3 

will cause the name “active” to be a selector for the latest main trank revisions of the three named files— 
that is, the latest revisions at the time the selection is made, not at the time the NameRevisions command 
was executed. Incidentally, if what was desired was the latest revision on branch “a” of, for example, 
valid2, that file name would be written in the NameRevisions command as “valid2,la”. If a revision is 
fully specified in a file name, e.g. “valid2,lal”, then that will be the selected revision, regardless of whether 
or not the dynamic option is used. 

If a NameRevisions command reuses a name, the file revisions named in that command will be appended to 
the list of those previous associated with the name. If the intent is to replace the old set of revisions by a 
new set, then the option -replace must be used. A name can be expunged by using it as an argument of 
the DeleteNames command. 
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Project Base/ 

# Make "we dries da/’ a private name for the latest revision of all 

# files in the project. 

nam erevisi ons -privat e-r -a Wednesday 

###nam erevisi ons -There are no files in project"Base/Interfaces/' 

###nam erevisi ons - T h ere are n o fil es in project" Bas e/S o urc es/" 

# C onfirm what happened: 

nam erevisi ons -privat e -r -s 

# Project: Base/ 

NameRevisions Wednesday -private-u’Herb Kannei* -project Base/d 
BuildScrfipt, la 
Make Fil ej 

# Project: Basejlnterfaces/C/ 

NameRevisions Wednesday -private-u ’Herb Kanner' -project Base/Interfaces/C/d 
Clnterfaces.hJ 

# Project: Bas e/Interfaces/C PI us/ 

Nam eRevisi ons Wednesday -privat e-u‘Herb Kanner'-project Bas e/lnterfaces/C PI us/a 
CPIusInterfaces.hJ 

# Project: Base/Sources/C/ 

NameRevisions Wednesday -private-u‘Herb Kanner*-project Base/Sources/C/a 
CSource1.c,5d 
CSource2.c,2d 
CSource3.c,2 

^Project: Base/Sources/CPIus/ 

NameRevisions Wednesday -private-u‘Herb Kanner*-project Base/Sources/CPIus/d 
CPIusSourcel.cJ a 



13 

B 


Fig. 27 


The application of NameRevisions is demonstrated in the next few illustrations. In Fie. 27, using the 
-r (recursive) option, the name “Wednesday” is associated with the all files in base/ and all of its 
subprojects. Note that two diagnostic messages are emitted about the subprojects that do not contain files. 
As in MountProject, omission of necessary parameters causes that command to emit information, but 
includes the command name itself for possible future use. So, using no parameters, the execution of the 
command with the -r option causes printouts of the NameRevisions commands for each level of the project 
hierarchy that would associate the name with the applicable revisions. The effect is to get a nice list of the 
exact revisions that would be selected by use of the name. 
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#Make“laJtesr a public dynamic name for all the files inthe project 
namerevisions -dynamic -r-a latest 
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# Project: Baae/ 
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NameReviaiona ve dnea day-private-u ‘Herb Kenner*-project BaaejlnterfaceajC/a 
CJnterfaces.hJ 

NameReviaiona lateat-u Herb Kannei* -project Baaejlnterfacea/C/a 
Clnterfaces.h, 

# Project: Baaejlnterfacea/CPIua/ 

NameReviaiona ve dnea day-private-u Herb Kenner* -proj ect Baaejlnterfacea/CPIua/d 
CPI uslnt effaces.h,1 

NameReviaiona lateat-u Herb Kenner* -project Basejlnterfaces/CPIus/e 
CPI uslnt erfaces.h, 

% Project: Baae/Sourcea/Cj 

NameReviaiona vedneaday-private-uHerb KanneK-project Baae/SourceajC/d 
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Fig. 28 


In Fig. 28, the exercise of Fig. 27 is repeated, but this time the name “latest” is defined to be a 
dynamic name. The parameterless NameRevisions command is now given an additional option, -b, which 
forces it to list both public and private name assignments. We get to see now the files associated with the 
public name “latest” and with the private name "Wednesday.” Note that the files associated with the 
dynamic name are indicated by the file name followed by a comma, but with no revision number. This is 
because a file selected by a dynamic name is automatically the latest main trunk revision, so it is not 
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usually desired to see the revision number. If the revision number is wanted, the option -expand will 
force it to appear as is demonstrated in Fig. 29. 
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MPV Shell 
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project base/sources/c 
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CSource1.c,d 

C$ource2.c,a 
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# Now use -expand option 


namerevisions -b -s -expand 
t Project: Base^ources/C/ 

NameRevisions latest-u Herb Kannei'-project Base/Sources/C/d 
CSource 1.c,3d 

CSource2.c / 2d 

CSource3.c # 2| 

O’ 


liililO 03 


Fig. 29 


If You Must Be Different 

The demonstrations given so far make the checkout directory mimic the structure of the project itself. 
Each individual user of the project is free, however, to structure the checked out files in any desired way. 
For example, the commands: 

CheckOutDir -project Basejsources/c scrprojector:CFiles 
CheckOutDir -project Basejlnterfacesjc sc:projector:CFiles 
CheckOutDir -project Base/SourcesJcPlus scrprojectorrCPlusFiles 
CheckOutDir -project BasejlnterfacesJcPlus scrprojectorrCPlusFiles 


will create directories “:CFiles:” and “:CPlusFiles:”, will cause all files in Base/Sources/Cj to be checked 
out in the directory “:CFiles:”, and so on. 


Comparing Revisions and Merging Branches 

We discuss here the last two items on the MPW menu bar under “Project.” The first, named 
“Compare Active...**, calls the script CompareRevisions. The second, named “Merge Active...”, calls the 
script MergeBranch. Both of these scripts do a small amount of housekeeping and call on the MPW script 
CompareFiles for the main body of the task. When “Compare Active” is invoked—the active window must 
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be a checked out projector file—a selector window will appear naming the revision number of the active 
window and listing all other revisions so that one can be chosen. When the desired revision has been 
chosen, CompareFiles goes into action, and its windows display all the differences between the two 
revisions. "Merge Active..." has a similar set of mechanisms and some constraints. The active window 
must be a branch revision. The other window, implicitly chosen, is the latest main trunk revision, checked 
out for modification. The mechanisms of CompareFiles permit the user to find the differences and selec¬ 
tively to copy and paste material from the branch to the main trunk. This is the method to be used when 
work on a branch proves to be fruitful and it is desired to incorporate that work into the main line of the 
project. For details on the behavior of CompareFiles, see Volume 2 of the MPW Reference Manual. 

A particularly simple case of the application of Merge Active is of frequent occurrence, and is worth 
examining in detail. Suppose we check out Revision 10 of a file for modification, apply a set of changes 
applied, and then check it back in. After some thought, we decide that the current revision, namely 
Revision 11, is absolutely worthless and that we would like to revert to the previous revision. Unfortu¬ 
nately, there is no way to delete a single revision from the top. The best that we can do is to create a 
Revision 12 that is a duplicate of Revision 10. Here is the quickest way to do this. In the Check Out 
window, “open” the file to show the revision list, chose Modifiable and Branch and then select Revision 10 
while holding down the option key. Press the Check Out button. A branch revision from 10 will be 
checked out Now open the file, so that the active window contains this revision. Select “Merge Active...” 
from the Project menu. When the machine has settled down, the following will be seen: At the top of the 
screen will be two windows, side by side. One of them will be read-only, and will be the branch lOal. The 
other will be read-write, and will be the modifiable Revision 11+. (Revision 11+ becomes Revision 12 
when checked in.) Inspection of the Check Out window will confirm the status of these windows. Now, 
do a “select all” operation, either via the Edit menu or from the keyboard, on both of these windows, and do 
a copy and paste of the entire branch window into the modifiable window. Next, select the pop-up item 
“Done” from the "Compare” menu item. This will dispose of the two windows. Finally, do a check in of 
the file, creating Revision 12. 


Miscellaneous Goodies 

Projector commands not yet considered are: 

DeleteRevisions 

ModifyReadOnly 

OrphanFiles 

Projectlnfo 

TransfeiCkid 

UnmountProject 

These are discussed briefly where the writer feels that some explanation is useful. Some of them are not 
mentioned at all on the grounds that the material in the MPW manual is adequate. 

DeleteRevisions does not do what one might expect It cannot usually be used to expunge a mistake. 
Its purpose is to delete large revision sets that are no longer wanted because of obsolescence. So, the alter¬ 
natives are: with the -file option, it will delete all revisions of the named file from a project. It will be as 
if the file had never been there. Without the file option, it deletes all revisions that are older than the named 
one on its branch, or an entire branch (see below). The obvious purpose is to get rid of stuff that is so old 
that no one will ever again want to see it. So, for example, 

DeleteRevisions -project projj file.c 

will delete all revisions of file.c prior to the latest one on the main trunk. If the parameter is 
file, c , 2a3, then all revisions on branch 2a prior to 2a3 will be deleted. If the parameter is 
file. c, 2a, then all of branch 2a will vanish. 

ModifyReadOnly is an emergency kind of command. Suppose a file has been checked out read only, 
and then the Projector database becomes temporarily unavailable. A typical situation causing this would be 
that the database is on a server, and the checkout is to a portable medium which the owner takes home. At 
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home, a decision is made to edit this file. ModifyReadonly will remove the read only restriction from the 
file. This change can be confirmed by that fact that the icon in the lower left comer of the file window 
changes. The solid line that crosses the pencil becomes a dotted line. When this file next confronts the 
Projector Check In window, this same modified icon will appear next to the file name, and it will be possi¬ 
ble to check the file in as a new revision. 

OrphanFiles is used to remove completely the Ckid resource from a file, so that the file is no longer 
recognized by Projector. 
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Command Syntax 


Checkin -w | -close | ([-u user] [-project project] [-t task] 

[~p] [-cs comment I -cf file] [-new | -b] [-m | -delete] 

[-touch] [-y | -n | -c] (-a | file...) ) 

Checkout -w | -close I ([-u user] [-project project] 

[[-m] [-b] | -cancel] [-t task] [-cs comment I -cf file] 

[-d directory] [-r] [-open] [-y | -n | -c] [-p] 

[-noTouch] (-update I -newer | -a | file...) ) 

CheckOutDir [-project project I -m] [-r] [-x | directory] 

CompareRevisions file 

DeleteNames [-u user] [-project project] [-public I -private] 
[-r] [names... I -a] 

DeleteRevisions [-u user] [-project project] [-file] [-y] 
revisi on... 

MergeBranch file 

Modify Readonly file... 

MountProject 

NameRevisions [-u user] [-project project] [-public I -private | 
-b][-r] [[-only] | name [[-expand] [-s] | [-replace] 

[-dynamic] [names... | -a] ] ] 

NewProject -w | -close | ([-u user] [-cs comment | -cf file] 

project) 

OrphanFiles file... 

Project [-q | projectname] 

Projectlnfo [-project project] [-log] [-comments] [-latest] [-f] 
[-r] [—s] [-only | -m] [-af author | -a author] 

[-df dates | -d dates] [-cf pattern | -c pattern] 

[-t pattern] [-n name] [-update | -newer] [path...] 

TransferCkid sourcefile destinationfile 

UnmountProject -a | project... 
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Part I Shell Reference 












Introduction: The New and the Necessary 


Welcome to the macintosh® Programmer’s workshop 3.0. This introduction is 
your guide to the new features and enhanced capabilities. 

Those currently using MPW™ 2.0 are urged to carefully review the section “What’s 
New in MPW 3.0” because many changes may affect your MPW 2.0 scripts and 
other ways of doing things. The last two sections of this introduction describe 
new hardware and software requirements as well as revised notation conventions 
and reorganized documentation. If you are new to MPW you can skip the “What’s 
New in MPW 3.0” section, but be sure to read “What You’ll Need” and “About This 
Reference.” This last section guides you to the parts of this book that help you 
get started. ■ 
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Power tools for Macintosh programmers 5 
What’s new in MPW 3.0 7 
MPW C++ 7 
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Symbolic Application Debugging Environment (SADE) 8 
New or enhanced tools 8 
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Power tools for Macintosh programmers 


The Macintosh Programmer’s Workshop (MPW) provides professional software 
development tools for the Apple® Macintosh computer. Briefly, MPW 3.0 consists of the 
following parts: 

■ MPW Shell (the programming environment) 

■ Project management system (Projector Trademark) 

■ Resource compiler and decompiler (Rez and DeRez) 

■ Resource editor (ResEdit™) 

■ Linker (Link) 

■ Make (for tracking file dependencies) 

■ Dialog interface (Commando) 

■ Symbolic Application Debugging Environment (SADE™, an interactive symbolic 
debugger) and MacsBug 

■ Performance-measurement tools 

Note that ResEdit, although still part of MPW, has been enhanced and is now documented 
separately. Also, the new interactive debugger, SADE, and an improved MacsBug are now 
each documented in their own separate reference works, included with the MPW product. 

The system also includes a comprehensive array of additional tools for creating and 
manipulating text and resource files. The following MPW products are separately 
available: 

■ Macintosh Programmer’s Workshop 3-0 Assembler provides everything you need 
to develop applications, tools, and desk accessories in assembly language, including 
the ability to create macro libraries. 

■ Macintosh Programmer’s Workshop 3.0 Pascal provides the additional tools, 
interfaces, and libraries you need to develop applications, tools, and desk accessories 
in Pascal. 

■ Macintosh Programmer’s Workshop 3.0 C provides a new C compiler and a C++ 
translator along with the interfaces and libraries needed to develop applications, 
tools, and desk accessories in C or C++. 

■ MacApp®, the Expandable Macintosh Application, provides of a set of object- 
oriented libraries that automatically implement the standard Macintosh user interface, 
thus simplifying and speeding up the process of software development Either MPW 
Pascal or MPW C++ is required for use of MacApp. 

The entire MPW system is oudined in detail in Chapter 1, “System Overview.” 
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The Macintosh Programmer’s Workshop 3.0 provides these advantages over previous 

development systems: 

■ Integration: The numerous utilities and tools of the MPW system all run within the 
MPW Shell environment. The integrated environment enables separately developed 
applications, called MPW tools, to run within the programming environment. The 
MPW editor is always available to generate both text and command lines; there is no 
distinction between command and text windows. 

■ MultiFinder™ compatibility: MPW 3.0 tools can now be operated in the 
background when using Macintosh System 6.02 with MultiFinder. This means that you 
can switch to another application while a tool, such as a compiler, is running. You can 
also configure your system so that you can use the MPW Shell for editing or other 
operations while a tool runs in the background. See “Using MPW With MultiFinder” in 
Chapter 2. 

■ Project management: Projector, a new program integrated with MPW, makes it easy 
to keep track of large projects involving many programmers, or simply to maintain an 
orderly revision history, showing who did what to every file and why. You can use 
Projector to branch, that is, create many experimental versions of a file at any stage 
in its evolution—without risk of confusion. 

■ Automated build process: A pull-down menu provides several ways to build or 
rebuild your programs quickly and automatically. You can also automate complex 
builds by using the Make tool and command-language scripts. 

■ Command scripting: In addition to menu commands, MPW provides a full command 
language, including Shell variables, command aliases, pipes, and the ability to redirect 
input and output You can combine any series of commands into an elaborate, 
specialized script (command file) for fast, accurate, automatic results. 

■ Regular expression processing: The editor component of the Shell provides 
powerful search and replace capabilities with regular expressions, which form a 
language for describing complex text patterns. Regular expressions allow you, for 
instance, to restructure complex tables with a single command. 

■ Extensibility: You can customize MPW in just about any way you can imagine. You 
can create your own integrated tools and scripts to run within the Shell environment. 
You can also add your own menus, menu items, and dialogs to the Shell. 

■ Ease of use: On-line help is available at all times. In addition, the Commando dialog 
interface gives you immediate on-screen access to all of MPWs versatile options and 
functions in specialized dialog boxes. This interface makes learning easier and faster. 
You can compose complex command lines without referring to the manual. And you 
can create a Commando interface for your own tools and scripts as well. 
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MPW 3.0 provides a customizable programming environment with a completeness, power, 
and flexibility unmatched by any other Macintosh-based system. Because it is full- 
featured and extremely versatile, the first-time user should be prepared to devote some 
time to leam it. This effort will be well repaid by the power and versatility that MPW 
places in your hands. 


What’s new in MPW 3.0 

MPW 3.0 is faster and easier to use than its predecessor and now fully exploits MultiFinder. 
Use of MPW with MultiFinder greatly increases its convenience and efficiency. Many new 
tools and options to existing tools have been added. Major additions to MPW include 
Projector, a project management system, and SADE, the Symbolic Application Debugging 
Environment MPW now also supports C++. These innovations are each briefly described 
in the sections that follow. Changes to menus, tools, variables, and compilers are itemized 
in the lists that follow. 

If you are currently using MPW 2.0, it is especially important that you carefully review the 
changes listed in this section. The extensive changes implemented in MPW 3.0 might 
affect scripts written for the MPW 2.0 Shell. 


MPW C++ 

MPW now includes extensions to the C language that support the features of C++. MPW 
C++ is an approximate superset of the C programming language that maintains the 
efficiency and power of C while adding features such as operator overloading (which lets 
you define additional meanings for built-in operators), ANSI-like type-checking, 
automatic type conversion, and class hierarchies with inheritance. Because C++ supports 
object-oriented programming, developers who prefer C to Pascal can now take advantage 
of MacApp. For more information, see MPW 3-0 C++ Reference. 
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Projector 

MPW 3.0 includes an easy-to-use, built-in project management system, Projector, that can 
be customized to fit any working style, from that of the single programmer to that of the 
large, networked engineering team. Briefly, here’s how it works: You check out a file or 
group of files from Projector for either review or modification. Although many people can 
review a file, only one person at a time can modify it. When you’ve finished your work, 
you check the file back in with Projector, along with a note detailing your modifications. 
Your name, your notes, and the date are automatically filed in Projector’s revision history 
for that project. It’s also possible to create parallel branches of a single project for 
experimental purposes. Chapter 7 is a detailed account of Projector. 


Symbolic Application Debugging Environment (SADE) 

The Symbolic Application Debugging Environment (SADE) allows you to monitor the 
execution of a program at both the processor level and at the symbolic program source 
level. Both SADE and the enhanced MacsBug are now each documented separately from 
the MPW Reference. For more information, see the MacsBug Reference and the SADE 
Reference. 


New or enhanced tools 

The tools and scripts included with MPW 3.0 have been improved in many ways for 
increased versatility. These enhancements are briefly catalogued in the list that follows. In 
addition, a number of new tools and scripts have been added to support Projector and 
the C++ compiler. 

MPW 3.0 supports shared tools on a network file server. 

These rarely used conversion tools are no longer included with MPW but are still available 
from Technical Support at Apple Computer, Inc.: 

■ TLACvt 

■ MDSCvt 

■ CVTObj 
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All MPW 3.0 commands, including tools and scripts, are individually documented in the 

alphabetically organized Command Reference in Part II of this book; that is the first 

place to look for more information about any tool. 

■ Backup: Two new options have been added. 

■ C: The C compiler has been completely rewritten for MPW 3.0. Some of the options 
and calling conventions are different from those in the MPW 2.0 C compiler. See the 
MPW 3-0 C Reference. 

■ CFront: New translator for C++. 

■ Choose: A new tool that enables you to mount servers and select Apple LaserWriter® 
printers from within the MPW environment. 

■ Commando: Now has a built-in editor that makes it easy to modify Commando 
dialog boxes. 

■ CompareFiles: A script that compares two files side by side, pinpointing any 
differences. 

■ CompareRevisions: A Projector script used to identify and compare revisions. See 
Chapter 7 for details. 

■ CPlus: New script that compiles C++ programs. 

■ CreateMake: Enhanced with a new option that supports SADE. 

■ Dolt: A script to highlight and execute a series of commands. 

■ DumpCode: Enhanced. 

■ DumpFile: New -bf option. Note that the -c option has been renamed -w (for width). 

■ DumpObj: Enhanced to support SADE. Two new options have been added. 

■ GetFfleName: Enhanced with a new -c (current) option to write the current Standard 
File pathname to standard output. The syntax of this command has also been 
improved. 

■ GetListltem: GetListltem now supports keyboard shortcuts and a new option: -s 
(single) option that permits only a single item to be selected from a displayed list. 

■ lib: Enhanced. Lib now determines the optimum buffer allocation from the amount 
of available memory; the old -b, -bs, -bf options are therefore obsolete and have been 
eliminated. 

■ Link: Enhanced to permit up to 1024 files, including both object files and symbolic 
debugger source file specifications. A new -map option produces a sophisticated link 
map. Link now determines the optimum buffer allocation from the amount of 
available memory; the old -b, -bs, -bf options are therefore obsolete and have been 
eliminated. A new option supports SADE. See Chapter 10. 
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■ MacsBug: MacsBug performance has been enhanced and upgraded. The MC68881 and 
MC68882 floating-point coprocessors are supported. See the separate MacsBug 
Reference. 

■ Make: Changes have been made to the way variables are treated. See “Variables in 
Makefiles” in Chapter 9. 

■ Matchlt: A new command that intelligently seeks the mate of a specified delimiter 
used in Pascal, C, or Assembler, allowing for loops, comment fields, nesting, and so 
on. 

■ MergeBranch: A Projector script used to help merge a branch file back into the trunk 
of a project. See Chapter 7 for details. 

■ Pascal: Enhanced with object-oriented capabilities. See the MPW Pascal section later 
in this chapter and the MPW 3.0 Pascal Reference. 

■ Print: Enhanced. A new option, -ps, lets you send a file of PostScript® commands to 
the LaserWriter™. 

■ ProcNames: This Pascal utility now generates Shell marker commands, allowing easy 
access to the procedure, function headers, or bodies. Names are now displayed 
indented to show their nesting level. Nesting level and line number are also displayed. 

■ Resource tools: The command language of Rez has been extended with the new 
syntax element Label to support color QuickDraw resources. There are a few new 
syntax rules, new options, and two new functions that allow you to delete resources or 
change resource information. See Chapter 11 and Appendix D. 

■ Sort: A new tool for sorting lines of text. 

■ Wherels: This new tool helps you find files hidden deep in a directory tree. You can 
use it to locate files when you know only a partial pathname. 


New or enhanced Shell commands 

All of these built-in commands are fully described in the Command Reference in Part II; 
that is the first place to look for more information. 

■ Checkin: New Projector command to check files in to a Project. See Chapter 7. 

■ Checkout: New Projector command to check files out from a Project. See Chapter 7. 

■ CheckOutDir: New Projector command to set Checkout directory. See Chapter 7. 

■ Close: Enhanced with a -c option; it lets you select the dialog’s Cancel button during a 
scripted operation. 

■ Date: Enhanced to provide “date arithmetic.” 

■ DeleteNames: New Projector command. See Chapter 7. 
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■ DeleteRevisions: New Projector command. See Chapter 7. 

■ Directory: A “directory path” variable (similar to the {Commands} variable) for 
changing current directories has been added. 

■ Evaluate: Enhanced to support different radices and variable assignments. 

■ Flush: A command for flushing tools from the tool cache. 

■ Format: A scriptable form of the format option in the Edit menu. 

■ FullBuild: Enhanced. 

■ ModifyReadOnly: New Projector command to make read-only files modifiable. See 
Chapter 7. 

■ MountProject: New Projector command. See Chapter 7. 

■ MoveWindow: Enhanced to provide current window size and position. 

■ NameRevisions: New Projector command to name revised projects. See Chapter 7. 

■ NewProjecfc New Projector command to create a new project. See Chapter 7. 

■ OrphanFiles: New Projector command. See Chapter 7. 

■ Position: This new command shows the current line number, beginning of selection, 
and end of selection in specified windows. 

■ Project: New Projector command. See Chapter 7. 

■ Projecting): New Projector command. See Chapter 7. 

■ Request: Enhanced with -q option to quiet any error messages, permitting a script to 
continue regardless of user input. 

■ RotateWindows: New command that sends the front window to the back. 

■ SizeWindow: Enhanced to provide current window size and position. 

■ StackWindows: Enhanced to support user-defined rectangles and a variable number 
of windows. 

■ TileWindows: Enhanced to support user-defined rectangles and a variable number of 
windows. 

■ TransferCkid: New Projector command. See Chapter 7. 

■ UmountProject: New Projector command. See Chapter 7. 
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New Shell editor capabilities 


The MPW Shell editor has been refined in various ways: 

MPW 3.0 supports the special keys on the Apple Extended Keyboard: 


Esc 
Undo 
Cut 
Copy 
Paste 
Help 

Home 

End 

Page Up 
Page Down 


Same as Cancel button in a dialog box 
Same as Undo menu command 
Same as Cut menu command 
Same as Copy menu command 
Same as Paste menu command 

With no selection, displays a summary of the Help available. With a 
selection, information on that selection is displayed. 

Equivalent to moving the vertical scroll box to the top of the scroll bar. 

Equivalent to moving the vertical scroll box to the bottom of the scroll 
bar. 

Equivalent to clicking the mouse pointer in the upper gray region of the 
vertical scroll bar. 

Equivalent to clicking the mouse pointer in the lower gray region of the 
vertical scroll bar. 


■ The displayed line-length limit has been increased to 256 characters. 

■ The tab-length limit has been increased to 100 characters. 

■ Horizontal scrolling is faster; more screen area is moved per mouse click. 

■ You can reverse the direction of the Find, Find and Replace, Find Same, Replace Same, 
and Find Selection functions by holding down the Shift key when selecting a menu 
item (or, in a dialog box, when clicking OK). This makes interactive searching a little 
more convenient but does not affect Shell search variables. 

■ Text selection by matching delimiters (such as {},(), [ ], and so on), has been 
modified. Instead of selecting the rest of the document when a matching character is 
not found, the delimiter at the position of the double-click is highlighted. During the 
search you can abort by pressing Command-Period. 

■ The new commands Format and Position (described above in the “New or Enhanced 
Shell Commands” section) are useful for scripted editing. 

■ The library routine f access has been enhanced to provide more programmatic 
control over Shell windows. 
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■ You can now disable Auto-Indent for one line by pressing Option-Return. 

■ The MPW Shell editor ignores any zero-width characters that are typed from the 
keyboard. (Usually these are typed by accident.) If you really want a control character 
in your document, you can enter it in the Key Caps desk accessory and then paste it in 
your document. To delete control characters that might not be visible, select Show 
Invisibles from the Format dialog box. All control characters are displayed as an 
inverse question mark ( i ). 


New standard Shell variables 

Twelve new variables have been added to give you control over almost all formatting and 
editing options from scripts. (Only display invisibles cannot be predefined.) The first five 
variables listed here provide default settings for new windows and are especially useful 
with large-screen monitors. See “Variables Defined in the Startup File” in Chapter 5 for 
more information. 

■ {Autoindent} sets default indenting for new windows. 

■ {Font} sets default font for new windows. 

■ {FontSize} sets default font size for new windows. 

■ {NewWindowRect} sets the default size for new windows. 

■ {ZoomWindowRect} sets default size for windows that are zoomed to full screen size. 

■ {TileOptions} sets options for the TileWindows menu item, for example, to specify a 
rectangle for the tiled window arrangement. 

■ {StackOptions} sets options for the StackWindows menu item, for example, to 
specify a rectangle for the stacked window arrangement. 

■ {SearchBackward} can be used to set your default environment to specify backward 
searching. 

■ {SearchType} can be used to set your default environment to specify searching for 
literal characters, words, or regular expressions. 

■ {SearchWrap) can be used to set your default environment to specify wrap-around 
searching. 
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■ {User} specifies the name of the user currently using MPW. It is predefined to be the 
same as the user name specified in the Chooser. 

■ {IgnoreCmdPeriod} is a new variable referenced by MPWs command interpreter. Use 
this variable in your scripts when you want any Command-Period input by the user to 
be ignored. 


Changes to menus and dialogs 

A few menus have been slightly changed since the release of MPW 2.0: 

■ TileWindows and StackWindows menu items now, by default, do not include the 
Worksheet. You can include the Worksheet in the tiling or stacking by pressing the 
Option key when selecting the TileWindows or StackWindows menu item. The 
fnieOptions} and {StackOptions} variables let you completely customize the 
operations of the TileWindows and StackWindows menu commands. See Chapter 3. 

■ Window menu now lists any open Projector windows. See Chapter 3. 

■ The Open dialog box now contains a Read Only checkbox. 


Miscellaneous Shell changes 

Here are some important improvements for the MPW Shell: 

■ MPW 3.0 supports background operation of tools while running MultiFinder. This is a 
significant improvement in convenience and efficiency. Please see “Using MPW With 
MultiFinder* in Chapter 2 for instructions on configuring your system for true 
multitasking. 

■ An automatic installation program is included with MPW 3.0. This program, Installer, 
and the tools to support it, can be found on the MPW Installation Disk. Please read 
“Installing the System” in Chapter 2 before doing anything with it. This is important 
because the arrangment of MPW files on the 3.5-inch distribution disks has been 
changed to represent their final destination when moved to a hard disk. Thus there 
will be some duplication of folders across the set of distribution disks so that you 
cannot simply copy the entire contents of a distribution disk without some conflict. 

■ The Startup file now executes UserStartup and then any file named UserStartup* name 
in the directory that contains the Shell. (Press Option-8 to obtain the • symbol.) If 
you have a customized UserStartup file, you may want to personalize it (for example, 
UserStaitup*Tom) so that when you install MPW 3.0 your customized file won’t be 
overwritten. 
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■ Standard output and diagnostic output can now be directed to the same place with 
the £ (Option-W) character, meaning: “The summation of all output... ” See 
“Redirecting Input and Output” in Chapter 5 for the new syntax. 

■ You can now use Option-Enter to invoke the Commando dialog boxes for commands. 
Alternatively, you can still type the command name, then the ellipsis character 
(Option-Semicolon), and then press Enter. 

■ A new directory path variable for changing current directories is now available from 
the Directory command. (See Part II.) 

■ Numeric variables have been added to the Shell command language. See the Evaluate 
command in Part II for details. 

■ The notation conventions of this reference have been slightly modified. The index has 
also been improved. See “About This Reference” at the end of this Introduction. 


Numeric libraries 

linking with numeric libraries has been simplified by placing certain conversion functions, 
such as num2dec , in CRuntime.o. A program that simply uses print f will no longer need 
to link with CSANElib.o. 

A new {AIncludes} macro file called SANEMacs881.a is provided as a migration aid for 
Macintosh II developers who seek even greater floating-point performance from their 
products by using SANE macros. With little modification of their source files, they can 
reassemble by using the 881 SANE macros and thereby generate a faster application that 
runs only on the Macintosh II. 
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MPW C and MPW C++ Include files 


The capitalization conventions for those functions that use Points or strings have been 

changed for MPW 3.0. These changes are itemized here: 

■ Those functions that call “glue” code to convert C strings to Pascal strings or 
dereference Points are now spelled with all lower case letters. 

■ The in-line versions of those function calls, those that do no conversions, are now 
spelled with mixed cases to match the conventions in Inside Macintosh. 

■ You will find in the Scripts folder a new script, CCvt, that changes source code to 
conform to the new standard spelling conventions. CCvt first backs up the original 
source and then uses two Canon dictionaries to change mixed case spellings to all 
lower case and all upper case spellings to mixed case. 

■ The syntax for ROM calls (A-traps) has been changed. The new syntax allows multiple 
instructions for “direct functions” and is more compatible with standard ANSI C and 
C++. 

■ The header files have been rewritten with function prototypes that allow ANSI C and 
C++ to do additional type-checking and code optimization. 

If you use MPW C, please see the MPW 3-0 C Reference for more information about 

interfaces. 


MPW Pascal 

The MPW 3.0 Pascal Compiler no longer provides the compiler directive $load and the 
option -z that were supported in MPW 2.0 Pascal. In addition to providing nearly all the 
capabilities described in the ANS Pascal Standard, MPW 3.0 Pascal expands the power 
and flexibility of Pascal programming with a range of new features and options: 

■ SADE, the symbolic debugger (-sym option), and MacsBug (-mbg option) are 
supported. 

■ A replacement for the $LOAD mechanism provides a more automatic and faster 
method (-noload, -dean, and -rebuild options). 

■ You can use character constants as valid string expressions. 

■ Symbol support for MacsBug has been extended and improved. 

■ Global data greater than 32K is now possible. 

■ The requirements for forward type references are more flexible. 
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MPW tool libraries 

MPW language libraries that control the MPW Shell were previously documented in their 

respective language references. All Shell-related routines are now combined in this 

reference. 

■ Use of the MPW cursor control routines and error file manager is now explained in 
Appendix F of this book. Examples are shown in both MPW C and MPW Pascal; 
Assembly programmers can use both. 

■ Use of the MPW Integrated Environment routines are documented in Chapter 12. The 
routines are explained for MPW Assembler, MPW C, and MPW Pascal. 

■ The Graf3D library is now documented in Appendix G. Each routine or function is 
explained for MPW C and MPW Pascal; Assembly programmers can use both. 

■ The calls required to use the performance-measurement tools are now included in 
Chapter 14 of this book. Examples are shown in MPW C, MPW Pascal, and MPW 
Assembler. 


What you’ll need 

This section describes the hardware and documentation you need to develop software 
with the Macintosh Programmer’s Workshop 3.0. 


Hardware and system requirements 

The Macintosh Programmer’s Workshop 3.0 can generate applications that run on any 
Macintosh, including the Macintosh II, Macintosh SE, Macintosh Plus, Macintosh 128K, 
Macintosh 512K and 512K enhanced, and Macintosh XL. 

However, the MPW 3.0 system requires, at the minimum, a Macintosh Plus with 2 
megabytes of RAM and a hard disk drive. MPW does not run on the Macintosh XL, the 
Macintosh 128K, the Macintosh 512K, or Macintosh 512K enhanced or on systems without 
hard disks. MPW 3.0 requires the 128K or 256K ROMs; it cannot execute on the older 64K 
ROMs. The ideal developmental system for use with MPW 3.0 is a Macintosh n with an 
80-megabyte SCSI hard disk drive, 4 or more megabytes of memory, and System 6.0.2 or 
later software with MultiFinder. 

In general, a small RAM cache of about 32K is useful. Use of MPW with Switcher™ is not 
supported. 
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MPW software is shipped on 800K disks. Although MPW 3-0 can still read from and write 
to disks that use the nonhierarchical filing system, MPW’s files must be kept on disks that 
use the hierarchical filing system (HFS). Hard disks, when used as boot disks, must be 
HFS volumes. 

Apple’s Macintosh peripherals, including the LaserWriter family of printers and the 
AppleShare® file server, are supported. 


System Folder requirements 

Please make sure that you are using System file Version 6.0.2 or later versions. 

MPW 3.0 requires these minimum system file versions: 

■ System file 6.0.2 

■ Finder 6.1 

■ Laser Prep 4.0 

■ ImageWriter® 2.6 

■ AppleTalk® ImageWriter 3.1 

■ LaserWriter 4.0 

These files are available on version 6.0.2 or later of the System Tools disk, and on the latest 
version of the Printer Installation disk. 


Documentation 

In addition to the MPW3.0 Reference , you should have the SADE Reference , the Macsbug 
Reference, and the ResEdit Reference. These books together make up the MPW 3.0 
documentation suite. 

The four MPW programming languages, MPW Assembler, MPW C, MPW C++, and MPW 
Pascal, are available as separate products. 

All programmers need Volumes HV of Inside Macintosh (published by Addison-Wesley, 
1985), the definitive guide to the Macintosh Operating System and user-interface 
toolbox. Additional features of the Macintosh SE and Macintosh II computers are 
documented in Volume V. If you need to understand and control the numeric 
environment, make sure that you have the Apple Numerics Manual, a guide to the 
Standard Apple Numerics Environment (SANE™). Finally, you need the appropriate 
documentation for the programming language you use: 


18 


MPW 3.0 Reference 











■ Assembly language: Macintosh Programmer's Workshop 3-0 Assembler Reference. 
This reference is part of a separate product available from Apple. You may also need 
the appropriate microprocessor documentation from Motorola. 

■ C: Macintosh Programmer’s Workshop 3-0 C Reference. This reference is available as 
part of a separate MPW product. For a guide to the C language itself, you’ll need The C 
Programming Language by B. Kemighan and D. Ritchie, or a similar C manual. 

■ C++: MPW 3.0 C++ Reference. Also recommended is The C++ Programming 
Language by Bjame Stroustroup. 

■ MacApp: MacApp Programmer’s Reference. This reference is part of a separate 
product, MacApp, the Expandable Macintosh Application, available from Apple. The 
MacApp product also requires MPW Pascal or MPW C++. 

■ MacsBug: MacsBug Reference. This reference is included as part of the MPW 3.0 
product. 

■ Pascal: Macintosh Programmer’s Workshop 3-0 Pascal Reference. This reference is 
available as part of a separate MPW product. 

■ ResEdlfc ResEdil Reference. This reference is included as part of the MPW 3.0 product. 

■ SADE: SADE Reference. This reference is included as part of the MPW 3.0 product. 


About this reference 

Part I of this book describes the MPW development system, including the Shell and tools. 
Part II of this book is a complete alphabetical reference to MPW commands that may be 
removed to a smaller binder for easy reference. 

This reference is written for programmers who are already familiar with the Macintosh. It 
outlines the process of building a program but does not deal with the particulars of writing 
it. Language-specific information is covered in the appropriate language references. 
Language-specific examples in this reference are given in MPW Assembler, MPW Pascal, or 
MPW C. 

If you are new to MPW, be sure to read the Overview in Chapter 1 and the brief section 
“Building a Program: An Introduction” in Chapter 2. This introduction will take you 
through MPW’s build process in minutes. Chapter 3 introduces the commands available 
from the menus and Chapter 4 covers the basics of using MPW, including features of the 
Commando dialog interface. 
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If you are a seasoned MPW user, this introduction should be sufficient to alert you to the 
changes to the MPW Shell since MPW 2.0, and to indicate where you can find complete 
details on each innovation. You may wish to read the new Chapter 7, “Projector: Project 
Management.” Please note that Link and Make are now described in their own chapters in 
this reference and that ResEdit and MacsBug are now documented in separate volumes. 
More examples have been added since MPW 2.0, and suggestions from readers have been 
incorporated to make it easier to find information. 


Finding information fast 

During MPW sessions, the on-line Help files included with MPW are your first recourse. If 
you don’t find the information you need there, the recommended procedure is to check 
the Table of Contents and then the index at the end of Part I in this reference. Use the 
color-keyed mbs to turn quickly to the section in the MPW Reference that you need. Then 
use the table of contents provided at the beginning of each chapter. 

The index has been redesigned for MPW 3.0. A single datum in the text (excluding 
appendixes and Part II) may be referenced from as many as six different points in the 
Index and up to three levels deep. References include practical task-oriented 
identification to help you find exacdy what you need without looking up a series of page 
references for a single word. Trivial references have been eliminated from the index to help 
you avoid wild-goose chases. Examples, tables, warnings, and special notes have been 
listed to help you find things you may have encountered before but can’t remember 
exactly where. 

Throughout this book you will encounter supplementary background information, hints, 
and tips in specially formatted boxes set off by diamond-shaped icons and sans-serif 
type. You can ignore these boxes during routine reference. 

In spite of redundancy and a plethora of cross references, finding a specific item of 
information in a book this size can sometimes be frustrating. A little preparation can help 
out later when you are busy and need to find something fast. It’s a good idea to begin by 
carefully studying the organization of the Contents pages, especially the List of Figures 
and Tables and the appendixes at the end of Part I. The List of Figures and Tables and the 
appendixes are often overlooked. You may find it useful to glue mbs at the locations of 
important figures and tables. Whenever you come across something in the body of the 
text that you think you may need to find later, place a mb there and label it. 
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Part II of this manual is a complete alphabetical reference to MPW commands. As you 
become familiar with MPW and no longer need to refer often to the indexed chapters of 
Part I, you may find it convenient to remove Part II and place it in a smaller binder for 
handy reference. You may want to include some of the appendixes (such as the summary 
of the Resource compiler's syntax in Appendix D) in the smaller binder also. 


Syntax notation 


The following syntax notation is used to describe MPW commands: 


code 


include 


nonterminal 

{FontSize} 

[ optional ] 
-o 

repeated... 

a I b 

(grouping) 


Courier text is used in examples to indicate characters that 
must appear in a command line exactly as shown. Special 
symbols (-, §, &, and so on) must also be entered exactly as 
shown. Command-line examples are always set off in separate 
paragraphs. 

Command-language identifiers and syntax elements are set in 
Courier to differentiate them from surrounding Garamond text 
(following the Kemighan and Ritchie notation conventions). 

Items in italics can be replaced by anything that matches their 
definition. When referred to in the text, variables normally 
appear in italics. 

Standard MPW Shell variables appear without spaces between 
braces. 

Brackets mean that the enclosed elements are optional. 

Hyphenated command-line options appear in boldface when 
mentioned in text. 

An ellipsis (...), when it appears in the text of this reference only, 
indicates that the preceding item can be repeated one or more 
times. Do not confuse this reference convention with the 
ellipsis command-line character (Option-Semicolon), used to 
invoke the Commando dialog interface. 

•A vertical bar indicates an either/or choice. 

Parentheses indicate grouping (useful with the I and... 
notation). 


This notation is also used in the output of the Help command. (See “The Help Command” 
in Chapter 4.) 
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Filenames and command names are not sensitive to case. By convention, they are shown 
with initial capital letters. Important terms are printed in boldface when they are first 
introduced and defined; these terms are also fully defined in the glossary. Proper names 
of key user-interface elements, such as the Shell, appear with initial capitals. Command- 
key or option-key commands (such as Option-L) are always defined in the text with 
capitals for clarity; nonetheless, the commands work with lower case letters. 


Aids to understanding 

Look for these visual cues throughout the manual: 

A Warning Warnings like this indicate potential problems, a 

A Important Text set off in this manner presents important information, a 

♦ Note: Text set off in this manner presents important points that should not be 

overlooked. 

♦ Hints 

Text set off in this manner in Helvetica type indicates practical hints or background 
information that need not be perused during routine reference. ♦ 


For more information 

APDA™ provides a wide range of technical products and documentation, from Apple and 
other suppliers, for programmers and developers who work on Apple equipment. (MPW is 
distributed through APDA.) For information about APDA, contact 

APDA 

Apple Computer, Inc. 

20525 Mariani Avenue, Mailstop 33-G 
Cupertino, CA 95014-6299 

1-800-282-APDA, or 1-800-282-2732 
Fax: 408-562-3971 
Telex: 171-576 

AppleLink: DEV.CHANNELS 

If you plan to develop hardware or software products for sale through retail channels, you 
can get valuable support from Apple Developer Programs. Write to 

Apple Developer Programs 
Apple Computer, Inc. 

20525 Mariani Avenue, Mailstop 51-W 
Cupertino, CA 95014-6299 
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Chapter 1 System Overview 


This chapter is a guide to the structure of the MPW 3.0 system and an 
introduction to its components. If you are new to MPW, this chapter will help you to 
get oriented. The MPW Shell commands and the MPW tools are grouped according 
to task each tool or command is briefly introduced and cross-referenced. ■ 
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The MPW Shell 


The MPW Shell is an application that provides an integrated, window-based environment 
for program editing, file manipulation, compiling, linking, and program execution. The 
other parts of the Macintosh Programmer’s Workshop 3.0—the language and resource 
compilers, debuggers, Projector, Commando, and other tools described below (except 
independent applications such as ResEdit)—operate within the Shell environment These 
tools accept input from files and Shell windows, and direct output to them. 

The Shell combines a command language, a text editor, the Commando user interface, and 
the Projector project-management system. You can enter commands in any window, even 
within an ordinary text file, or you an execute them by using menus and dialogs. (A 
dialog may include one or more dialog boxes, which may in turn contain text boxes, 
check boxes, radio buttons, and so on.) For every MPW tool there is a Commando dialog 
offering all parameters, functions, and options of the command language along with built- 
in context-sensitive help. 

The command language provides text-editing and program-execution functions, including 
parameters to programs, scripting (command file) capabilities, input/output redirection, 
and structured commands. You run a tool by typing its name, and then a list of options 
and affected files. You an link tools together in custom scripts, piping the output of one 
to the input of another, thereby automating complex operations. 

The window operations, menus, and menu items are easily customized to fit your specific 
needs or preferences. 

The MPW Shell integrates the following functional components: 

■ An editor for creating and modifying text files. The editor implements normal 
Macintosh-style editing together with scriptable editing commands so that you an 
program the Shell to perform editing functions. (See Chapters 3, 4, and 6.) 

■ A command interpreter interprets and executes the commands you enter in a 
window or rad from a file. (See Chapter 5 and Part II.) 

■ The Commando user interface displays dialog boxes providing immediate, mouse 
access to all of MPWs many functions, features, and options, including on-line help. 
(Sec Chapter 4 for an introduction to the use of the Commando dialogs. Chapter 13 is 
a guide to creating and editing your own Commando dialogs.) 
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■ A command interpreter interprets and executes the commands you enter in a 
window or read from a file. (See Chapter 5 and Part II.) 

■ The Commando user interface displays dialog boxes providing immediate, mouse 
access to all of MPWs many functions, features, and options, including on-line help. 
(See Chapter 4 for an introduction to the use of the Commando dialogs. Chapter 13 is 
a guide to creating and editing your own Commando dialogs.) 

■ Built-in commands, in addition to editing functions, include commands for 
managing files without returning to the Finder, commands for manipulating windows, 
processing variables, command control flow, and more. (See Chapter 5.) 

■ Projector, a project-management system, makes it easy to track the revision 
history of even large projects with many contributors, with or without a network. 
Projector helps you avoid confusing versions or getting out of synch with colleagues. 
(See Chapter 7.) 

■ The MPW tools, over 135 versatile programming tools and scripts designed to run 
within the MPW environment Every tool is equipped with a complete dialog interface 
including context sensitive help. Part II of this reference is an alphabetically organized 
guide to each of these tools and their many options. 


Window commands 


All work in MPW is done within windows. The following commands are available for 
manipulating windows: 


Close 

MoveWindow 

New 

Open 

Rotate Windows 

SizeWindow 

Stack Windows 

Target 

TileWindows 

Windows 

ZoomWindow 


Close a window. 

Move window to a specified location on screen. 

Open a new window. 

Open a window. 

Rotate the sequence of a tiled or stacked array of windows. 
Set a window’s dimensions. 

Arrange open windows in a staggered diagonal array. 

Make a window the target window. 

Arrange open windows in a tile pattern. 

List windows. 

Enlarge or reduce a selected window. 
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File-management commands 

The MPW Shell provides the following tools and built-in commands for manipulating files 
and directories without having to exit to the Finder (see the MPW tool section later in this 
chapter for other commands that help to manage files): 


Backup 

Back up folder files. 

Catenate 

Concatenate files. 

Delete 

Delete files and directories. 

Directory 

Set the default directory. 

Duplicate 

Duplicate files and directories. 

Eject 

Eject volumes. 

Equal 

Compare files and directories. 

Erase 

Initialize volumes. 

Exists 

Find out if a file or directory exists. 

Files 

List files and directories. 

Mount 

Mount volumes. 

Move 

Move files and directories. 

Newer 

Compare two files to see which was modified most recently. 

NewFolder 

Create a directory. 

Rename 

Rename files and directories. 

Save 

Save files in edit windows. 

SetFile 

Set file attributes. 

Sort 

Sort or merge files. 

Unmount 

Unmount volumes. 

Volumes 

List mounted volumes. 

Which 

Determine which file (pathname) the Shell will execute. 
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Project-management commands 


Projector provides the following built-in commands and scripts, for managing projects and 
tracking revisions. See Chapter 7 for a complete explanation of Projector. 


Checkin 

Checkout 

CheckOutDir 

CompareRevisions 

DeleteRevisions 

DeleteNames 

MergeBranch 

ModifyReadOnly 

MountProject 

NameRevisions 

NewProject 

OrphanFile 

Project 

Projectlnfo 

TransferCKID 

UnmountProject 


Add or return files to a project. 

Check out a file for reading only or for modification. 

Set location of Checkout directory. 

Compare two revisions of a file in a project. 

Delete selected revisions and branches of the named files. 
Delete user-defined symbolic names. 

Merge a branch revision onto the trunk 

Change a file checked out as read-only to allow modification. 

Add the pathname of a project to the root project list. 

Name a set of revisions for the files of a project 
Create a new project directory. 

Orphan a file from a project. 

Set or write the current project. 

List current state of all files within a project 

Transfer resource information in one Projector file to another. 

Remove the pathname of a project from the root project list 
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Editing commands 

Besides the Macintosh’s usual mouse-and-menu editing capabilities, a number of built-in 
editing commands are provided. You can use these commands both interactively and in 
scripts. Editing commands feature the use of regular expressions, a set of special 
operators that forms a powerful language for defining text patterns. Other useful 
commands for editing (such as Matchlt and Translate) are listed later in this chapter under 
“MPW tools.” See “Pattern Matching” in Chapter 6 for a discussion of regular expressions. 


Adjust 

Adjust lines. 

Align 

Align text to left margin. 

Clear 

Delete the selection. 

Copy 

Copy the selection to the Clipboard. 

Cut 

Copy the selection to the Clipboard and delete the selection. 

Find 

Find and select a text pattern. 

Format 

Specify format of a file (font, tabs, font size). 

Mark 

Mark and name a text selection. 

Markers 

List marked selections. 

Paste 

Replace the selection with contents of the Clipboard. 

Position 

List the position of selections in a window. 

Replace 

Replace the selection. 

Revert 

Revert to saved file. 

Undo 

Undo last edit 

Unmark 

Remove a marker from its text selection. 


Structured commands 


The Shell also provides a number of built-in structured commands. Used mainly in scripts, 
these commands provide conditional execution and looping capabilities: 


Begin... End 

Break 

Continue 

Exit 

For... 

If... 

Loop... End 


Group commands. 

Break from For or Loop. 

Continue with next iteration of For or Loop. 
Exit from a script. 

Repeat commands once per parameter. 
Conditional command execution. 

Repeat commands until Break. 
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Other built-in commands 


The MPW Shell also provides a number of other predefined commands: 


AddMenu 

Alert 

Alias 

Beep 

Confirm 

Date 

DeleteMenu 

Echo 

Evaluate 

Execute 

Export 

Flush 

Help 

Parameters 

Quit 

Quote 

Request 

Set 

Shift 

ShutDown 

Unalias 

Unexport 

Unset 


Add menu item. 

Display alert box. 

Define alternate command names. 

Generate tones. 

Display confirmation dialog box. 

Write the date and time. 

Delete a user-defined menu or item. 

Echo parameters. 

Evaluate an expression. 

Execute a script without affecting variable scope. 
Make variables available to programs and scripts. 
Clear the command cache. 

Display summary information. 

Identify parameters. 

Quit MPW. 

Echo parameters, quoting if needed. 

Request text from a dialog box. 

Define and write Shell variables. 

Renumber script positional parameters. 

Shut down or reboot machine. 

Remove aliases. 

Remove variable definition from export list. 
Remove Shell variables. 
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MPW scripts 


The menu commands available in the Directory and Build menus use some of these scripts: 


BuildCommands 

BuildMenu 

BuildProgram 

CCvt 

CompareFiles 

CompareRevisions 

CPlus 

CreateMake 

DirectoryMenu 

Dolt 

Line 

MergeBranch 

OrphanFile 

SetDirectory 

TransferCKID 


Show build commands. 

Create the Build menu. 

Build the specified program. 

Convert pre-3.0 C source to 3.0-compatible source. 

Compare two files side by side, pinpointing any differences. 
Identify and compare project revisions. 

Compile C++ programs. 

Create a simple makefile. 

Create the Directory menu. 

Highlight and execute a series of commands. 

Find, specified line in file. 

Merge a branch file back into the trunk of a project. 

Orphan a file from a project. 

Set current directory (from Directory menu). 

Transfer resource information in one Projector file to another. 
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MPW tools 


MPW tools are programs that run within the Shell environment. With the exception of the 
language compilers, the tools listed here are included with the Macintosh Programmer’s 
Workshop 30; several are described in more detail in the sections that follow. 


Asm 

Backup 

C 

Canon 

CFront 

Choose 

Compare 

Count 

DeRez 

DumpCode 

DumpFile 

DumpObj 

Entab 

FileDiv 

GetErrorText 

GetFileName 

GetListltem 

Lib 

Link 

Make 

MakeErrorFile 

Matchlt 

Pascal 

PasMat 

PasRef 

PerformReport 

Print 

ProcNames 

ResEqual 

Rez 

RezDet 


MC68000-family Macro Assembler (available as a separate product). 
Back up folder files. 

C compiler (available as a separate product). 

Canonical spelling tool. 

Translator for C++. 

Choose or list volumes or printers (scriptable chooser). 

Compare text files. 

Count lines and characters. 

Resource decompiler. 

Dump code resources. 

Display contents of an arbitrary file as hex and ASCII. 

Dump object files. 

Convert runs of spaces to tabs. 

Divide a file into several smaller files. 

Display text for system error numbers. 

Display a standard file dialog box. 

Present file selection list in dialog box. 

Combine object files into a library file. 

Link an application, tool, or resource. 

Program maintenance tool. 

Create error message textfile. 

Match paired language delimiters. 

Pascal compiler (available as a separate product). 

Pascal program formatter (part of MPW Pascal). 

Pascal cross-referencer (part of MPW Pascal). 

Generate a report analyzing program performance. 

Print text files. 

Display Pascal procedure and functions names (part of MPW Pascal). 
Compare files on a resource-by-resource basis. 

Resource compiler. 

Detect inconsistencies in resources. 
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Search 

Search files for a pattern. 

SetPrivilege 

Set access privileges to folders on file server. 

SetVersion 

Maintain version and revision numbers. 

Sort 

Sort files. 

Translate 

Convert one or more characters. 

Wherels 

Locate files buried deep in a directory tree. 


MPW Assembler 

The Assembler is provided as a separate product, MPW 3.0 Assembler, which includes the 

following: 

■ Translation of MC68000, MC68010, MC68020, and MC68030 assembly-language 
programs into object code 

■ Support for MC68881 and MC68882 floating-point instructions and MC68851 memory 
management instructions 

■ Powerful macro facilities, code and data modules, and entry points, local labels, and 
(optional) optimized instruction selection 

■ Assembly-language interfaces to Inside Macintosh routines 

■ Sample programs 


MPW Pascal tools 

The Pascal system is provided as a separate product, MPW 3.0 Pascal, which includes the 
following: 

■ Pascal compiler 

■ Pascal cross-reference program (PasRef) 

■ Pascal source file format program (PasMat) 

■ Pascal procedure and name program (ProcNames) 

■ Pascal runtime library 

■ Pascal interfaces to the Inside Macintosh routines 

■ Sample programs 

Macintosh Programmer’s Workshop 3-0 Pascal is an improved version of MPW 2.0 Pascal. 
The Pascal tools PasRef, PasMat, ProcNames, and the Pascal compiler are also 
documented in Part II of this reference. 
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MFW C compiler and C++ translator 

The C compiler and C++ translator are provided as separate products. MPW 3.0 C includes 
the following: 

■ C compiler 

■ Standard C Library 

■ C interfaces to the Inside Macintosh libraries 

■ Sample programs in MPW C 

The C Compiler implements the full C language as defined in The C Programming 
Language, by Brian Kemighan and Dennis Ritchie. The usual extensions to this definition 
provide enumerated types and structure assignment, parameters, and function results. In 
addition, Apple extensions provide SANE numerics and interfaces to Pascal functions and 
Macintosh traps. The compiler supports many ANSI C features, such as function 
prototypes and strict pointer compatibility. Most Standard C Library functions, including 
character and string processing, memory allocation, and formatted input/output, are also 
provided. 

MPW 3.0 C++ includes the following: 

■ C++ translator (CFront) 

■ C++ Streams Library 

■ Sample programs in MPW C++ 

The CFront translator from AT&T implements the full C++ language as defined in The C++ 
Programming Language, by Bjame Stroustroup. The current version, CFront 2.0, also 
implements multiple inheritance and other extensions described in the paper “Evolution 
of C++ from 1985 to 1987” by Bjame Stroustroup. In addition to the C extensions listed 
in that paper, C++ also contains extensions that allow C++ to be used with MacApp. 


Link 

The linker (Link) combines object code files into executable programs, driver resources, 
or stand-alone code resources. Link includes, by default, only the code and data modules 
that are referenced. Link replaces the code segments in an existing resource file, without 
disturbing other resources in the file. An option directs Link to produce a link map as a 
text file. Other options allow the creation of an object module cross-reference file, a file 
containing a list of all the unreferenced modules, and a symbolic debugger file. 
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A separate tool, Lib, provides library manipulation. Linking is performed automatically 
for simple programs constructed by using the Build menu. Chapter 8 describes the use of 
Link in building a program. See Chapter 10 for more details on the operation of the linker. 


Make 

The Make tool simplifies software construction and maintenance. Its input is a list of 
dependencies between files and instructions for building each of the files. Make generates 
commands to build specified target files, rebuilding only those components that are out- 
of-date with respect to their dependencies. You can generate makefiles automatically 
from commands in the Build menu. To use Make with more elaborate programs, see 
Chapter 9- 

Throughout this reference examples demonstrating Make or makefiles assume that you are 
using Apple’s MPW languages. Because Make assumes certain default rules that apply only 
to Apple’s MPW languages, you may need to make modifications for non-Apple 
programming languages. Please consult your compiler’s documentation for instructions on 
how to modify these default rules. 


Resource compiler and decompiler 

The resource compiler (Rez) reads a textual description of a resource and converts it into 
a standard Macintosh resource file. The resource decompiler (DeRez) converts resources 
into a textual representation that can be edited in the Shell, and recompiled with Rez. You 
can use DeRez to create resource compiler input from any existing resource files. Rez and 
DeRez need templates (type declarations) to define resource types. Definitions of the 
standard Macintosh resource types (' MENU •, 'STR#', 'ICON', and so on) are provided 
in two commented text files, Types.r and SysTypes.r. Another tool, RezDet, checks 
resource files for consistency (see Part II). Rez and DeRez are documented in Chapter 11. 

Rea’s capabilities have been extended in MPW 3.0. Two new functions let you delete 
resources or change resource types from within Rez. The new syntax element Label has 
been supplied to support more complex resources, such as those found in color 
QuickDraw. 
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Commando 


The Commando tool implements the Commando dialog user interface for all MPW tools 
and commands. Obviously, this is a great convenience for dealing with tools offering 
many interdependent options. Newcomers to MPW will appreciate Commando’s instant 
assistance in building complex command lines. The dialogs include a Help frame with 
information on each selected data field or control. You can also use Commando to create 
specialized dialogs for your own MPW tools and scripts. 

Commando looks in a tool’s or script’s resource fork for a resource of the type «cmdo». 
Commando then loads the resource, builds a dialog, handles events, and passes the 
resulting command line back to the Shell for execution. The basics of using Commando 
dialogs are described in Chapter 4. Dialogs utilizing specialized types of dialog boxes are 
presented with the tools they support in Part II. Chapter 13 tells you how to create a 
Commando interface for your own tools and scripts. 


Projector 

Projector is an easy-to-use project-management system that can be customized to fit any 
working style, from the single programmer to the large networked engineering team. Use 
Projector’s file-locking feature to control changes to master files, track a project’s 
revision history, and generally keep your projects organized. 

Briefly, here’s how it works: You begin a work period by checking out a file from 
Projector for either review or modification. Although many people can review a file, only 
one person at a time can modify a file. When you’ve finished your work, you check any 
modified files back in with Projector, along with a note detailing your modifications. 
Your name, your notes, and the date are automatically filed in Projector’s revision history 
for that project Various branches of a file containing different modifications may be 
later merged into one master file. 

Projector’s commands (listed in the section “Project-Management Commands” earlier in 
this chapter) are built into the Shell. Chapter 7 is a detailed account of Projector. 
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Conversion tools 

Canon is a tool for regularizing the spelling and capitalization of identifiers in source files 
moved from other systems. (In MPW languages, all characters are significant rather than 
just the first eight as in the Lisa Workshop. In C, case is also important.) 

The file Canon.dict contains the correct spelling and capitalization for Inside Macintosh 
ROM routines. C programmers, in particular, will find Canon and Canon.dict useful. 

Entab is a useful tool for converting space characters and tabs to conform to MPW editor 
or other editor conventions. 

You can look up these conversion tools in Part II. 


Performance-measurement tools 

The performance-measurement tools enable you to pinpoint where your code is spending 
time. These libraries allow you to sample the program counter, produce a file of output 
data, and analyze that data with a report generator. Advanced programmers will find these 
tools useful for streamlining the execution of their code. Chapter 14 is devoted to this 
subject. Examples of the actual calls and procedures are presented in MPW C and MPW 
Pascal. 


Applications 

Applications are stand-alone programs that can execute outside the Shell environment 
SADE and ResEdit are both stand-alone programs provided with MPW. It is assumed that 
you already have the Font/DA Mover, which is distributed on the system tools and system 
installation disks. Any application can be executed from the MPW Shell. 
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ResEdit 


ResEdit is an interactive, graphically based editor for creating, editing, and copying 
resources. An interface like that in the MacDraw application is provided to help you 
design your own fonts. ResEdit includes a set of routines that make it possible to write 
your own add-on resource editors for ResEdit. See the separate ResEdit Reference for a 
thorough explanation of ResEdit. 


SADE and MacsBug 


The new Symbolic Application Debugging Environment (SADE) is a symbolic debugger 
with an interactive graphic interface like that of the MPW Shell. SADE is an application 
that runs under MultiFinder and can be used to debug other applications and MPW tools. 
You can monitor the execution of your program simultaneously at the processor level and 
the symbolic program source level. This first release of SADE includes 

■ source display 

■ variable display according to type 

■ display of Macintosh system structure 

■ source level breaks and stepping 

■ programmable, extensible command language 

SADE is included with MPW 3.0 but documented separately in the SADE Reference. See 
Appendix F of this reference for the object file format. 

The familiar MacsBug has been improved for MPW 3.0, and is also documented in a 
separate volume, MacsBug Reference. 

MacsBug fully supports the MC68000, MC68020, and MC68030 processors, as well as the 
MC68881, MC68881, and MC68851 coprocessors. MacsBug resides in RAM together with 
your program. MacsBug allows you to examine memory, trace through a program, or set up 
break conditions and execute a program until they occur. MacsBug runs on all Macintosh 
computers with 128K or larger ROMs, including the Macintosh SE and Macintosh II. See 
the MacsBug Reference for instructions on using MacsBug. 
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Special scripts 

Several special command scripts are provided. They are essential for operation of the 
MPW Shell. These text files contain commands that are read by the Shell at startup and 
shutdown: 

■ The Startup file is a command script that calls another script, UserStartup, that is run 
each time you start the MPW Shell. You can use UserStartup to customize MPW. The 
Startup file now executes UserStartup and then any file named UserStartup* name in 
the directory that contains the Shell. (Press Option-8 to obtain the • symbol.) If you 
have a customized UserStartup file, you may want to personalize it (for example, 
UserStaitup»Tom) so that when you install MPW 3.0 your customized file won’t be 
overwritten. The Startup file is discussed in detail in Chapter 5. 

■ The Suspend and Resume files are scripts that preserve the state of the Shell 
environment while a stand-alone application is executing. The Quit file saves the state 
of the Shell environment when you exit to the Finder. 


Examples 

In addition to the examples excerpted in this reference work, you’ll find numerous 
complete examples in the Examples folder included on the MPW distribution disks. The 
examples are written in MPW C, MPW Pascal, and MPW Assembler. Examples illustrating 
the use of Projector are also included in this folder. If you are using a different compiler 
sold with MPW 3.0, check the compiler’s documentation and distribution disks for 
specific versions of these sample programs. See Appendix A for the location of the MPW 
3.0 Examples folder. 


Sample program files 

Source files are provided for sample MPW tools and desk accessories. Versions of these 
sample programs are included in MPW Assembler, MPW C, and MPW Pascal. They can be 
found in the Examples folder. The Examples folder also contains instruction files and 
makefiles for building the sample programs. Some of these examples are referred to in 
Chapter 2, “Building A Program: An Introduction.” 

Note that these sample files are part of the respective MPW C, MPW Pascal, and MPW 
Assembler products. 
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Command-language examples 

Examples of the use of the MPW command language are provided in the folder Examples. 
Among these are 

■ addmenu commands for creating user-defined menu items 

■ a list of UNIX-oriented aliases 

■ suggestions for modifying the Startup script 

To leam more about these examples, open the file Instructions in the Examples folder. 
Additional examples are included with each of the MPW commands in Part n of this 
reference. The command language is documented in Chapter 5. 



Overview of MPW files and directories 

Appendix A contains a complete list of all of the Macintosh Workshop 3.0 files. It also 
describes the recommended setup of files on a hard disk. Figure 1-1 shows the MPW folder 
layout. Folders for the Pascal, C, and Assembler systems are also shown, along with folders 
for your applications and projects. 


■ Figure 1-1 Setup of MPW folders and files 
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Be sure to see “Installing the System” in Chapter 2. 
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Chapter 2 Getting Started 


This chapter explains how to start using Macintosh Programmer’s workshop 
3.0. Even if you are familiar with MPW 2.0, it’s a good idea to read the next 
section that describes the new automated installation procedure. (You might run 
into some pathname conflicts if you simply drag files from the 3.5-inch disk to 
your hard disk.) This chapter also contains the section “Using MPW With 
MultiFinder, which explains how to use MPW while running a compiler in the 
background. You’ll also find a section with guidelines for sharing MPW from a file 
server. 

Basic rules of operation are introduced here and in Chapters 3 and 4. If you are 
new to MPW, the tutorial “Building a Program; An Introduction,” later in this 
chapter, will introduce you to the simplicity of using this environment. ■ 
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Installing the system 


Macintosh Programmer’s Workshop 3-0 is shipped on five 800K disks: MPW1, MPW2, 
MPW3, MPW4, and the MPWInstallation Disk. (MPW Assembler, MPWPascal, MPWC, and 
MPW C++ are separate products.) 

Before attempting to install MPW, please check the section “Hardware and System 
Requirements” in the Introduction of this book. 

Appendix A, “Macintosh Programmer’s Workshop Files,” contains an annotated list of 
MPW files and shows the recommended arrangement of files on a hard disk. Pathname 
rules for the Hierarchical File System (HFS) are explained later in this chapter. Also see 
Figure 1-1 at the end of Chapter 1 for a suggested arrangement of MPW folders and files. 

A complete MPW 3.0 system, including all three MPW languages, requires over 6 megabytes 
of disk space. 

MPW 3.0 includes an Installer script on the MPW Installation Disk, for systematically 
installing the complete MPW system from the other four disks so that everything is 
located in the folders that MPW expects. You need at least 6 megabytes of space on your 
HFS hard disk to complete the full installation. However, the Installer does give you the 
option of stopping the installation before all of the tools on disks MPW3 and MPW4 have 
been installed. 


A Warning Don’t simply drag the MPW Shell or any other files from the Installer 
disk to your hard disk. The files on the Installer disk are used for 
automatic installation only, and thereafter you’ll discard them. ▲ 


To automatically install MPW 3.0, follow these steps: 

1. Insert the MPW Installer disk in the 3.5-inch disk drive. 

2. Drag the Installation folder to your hard disk. If you have multiple hard disks, drag the 
folder to the hard disk on which you want MPW to reside. 

3. Open the folder and double-click the icon labeled “MPW Installer.” 

4. The first Installer dialog box appears: 
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This is the installation procedure for MPUJ 3.0. 
“InternahMPLU:” uiill be installed. Insert the first 
MPUI distribution disk in driue 1 and click OK. 

Cancel ] 



5. Click OK and insert the distribution disks in any order. The Installer program creates a 
folder named MPW at the root directory of the volume in which the Installer folder is 
located. 

6. When the installation is complete, or when you have clicked a Cancel button, the 
Installer quits the Shell. Now throw away the Installation folder. You are left with MPW 
in a folder at the root directory, ready to go. 

The order in which the disks are copied doesn’t matter, and it’s okay to insert the same 
disk more than once. You may also choose to stop by clicking the No button before 
you’ve copied all the distribution disks. 

If you decide to click the Cancel button for any reason, the MPW Shell Worksheet 
appears. (In that case, after quitting MPW, don’t save the Worksheet file that was created 
during the installation. It’s better to start all over again.) 

A Warning Don’t use apostrophes or any other special characters in the hard disk 
volume name. This would cause the Installer to fail. ▲ 


Using MPW with MultiFinder 


It would be very convenient to be able to work in the Shell or editor while waiting for a 
compiler to run in the background. But MultiFinder lets you switch to different 
applications only while running a tool; you cannot normally work in the Shell or editor 
while running a tool in the background. 

However, you can obtain this virtual multitasking capability by configuring a second 
MPW Shell. You work in the second Shell while the first maintains the background 
operation of any tool or script. Here is a way to set up the second MPW Shell: 
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Create a folder called Concurrent MPW and put these files in it 

■ MPW Shell 

Be sure to rename the second MPW Shell in this directory to something like 
“Concurrent Shell” or perhaps “MPW Editing Shell” so that you can quickly identify 
which Shell you are currendy using. 

■ Startup 

■ UserStartup 

This file isn’t crucial, but without the variables, aliases, and menus defined in your 
UserStartup, the Concurrent Shell would not be configured to your normal working 
environment. 

■ MFW.Help 

Alternatively, you could keep just one copy of MPW.Help in your main MPW directory 
and use an alias in your Edit MPW. For example: alias help 'help -f HD:MPW:MPW.help'. 

■ SysErrs.Err 

If you get an error from MPW and don’t have a copy of this file, you’ll see an error 
message such as: 

# OS error -43 (Error message file not available) 

■ Quit 

You can now use this second MPW Shell system while tools are running concurrently in the 
first MPW Shell. This configuration is only a suggestion. You could simplify it a bit,as 
indicated in the preceding notes. Also, the memory size in the second Shell may be 
decreased to 512K if it is used only for editing and small tools. 


♦ Note: Although you cannot move Shell windows or pull down menus while a tool is 
running, remember that you can switch applications by clicking the application icon in 
the menu bar. 


The same file cannot be opened for editing by both Shells at the same time. 

It’s a good idea to generate a sound (using Beep or other tools) at the end of scripts so 
that you know when your background operations are completed. 
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Using MPW on a file server 

To set up MPW in a shared environment, install the MPW system on the file server. The 
following files must reside on each workstation that shares the MPW system. 

■ MPW Shell 

■ Startup 

■ UserStartup 

Alternatively, you can change Startup to execute a UserStartup on the file server. 

■ MPWJHelp 

Alternatively, you can keep just one copy of MPW.Help on the file server by setting an 
alias in your Startup file. For example: 

alias help 'help -f SharedServer:MPW:MPW.Help* 

■ SysErrs.Err 

If you get an error from MPW and don’t have a copy of this file, you’ll see an error 
message such as: 

# OS error -43 (Error message file not available) 

■ Suspend/Resume 

You need these files only if you are not running MultiFinder. 

■ Quit 


Starting up 

Start up MPW just as you would start any standard Macintosh application. 

♦ Note: A small RAM cache (perhaps 32K) is useful when running MPW 3.0. You may use 
larger caches if you have plenty of memory. However, some functions in MPW 3.0 may 
run more slowly with large RAM caches. Use of MPW with Switcher is not 
recommended; use MultiFinder. 
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From the Finder, select and open the MPW Shell icon. The Worksheet window (shown in 
Figure 2-1) will appear with its full pathname in the title bar (for example, 
“HD:MPW:Worksheet”). This window has no close box and is always present on the 
screen; otherwise it’s just like any other window. The Worksheet is your home base. You’ll 
use it most often to type commands and see the return output. You can also write and 
compile sections of code or keep a diary—anything in the Worksheet can be saved to any 
window or file. 

You can also start MPW by double-clicking any MPW document or tool. 


■ Figure 2-1 Worksheet window 



The menus available from the Shell appear in the menu bar at the top of the screen. An 
explanation of each menu is provided in Chapter 3. You can easily add your own menu 
names. (See Chapter 8.) 

A status panel at the window’s lower-left comer shows the name of the command that’s 
currendy executing, or simply “MPW Shell” when you’re not executing a command. A 
mouse click on the status panel is equivalent to pressing the Enter key. 

When you first start the Macintosh Programmer’s Workshop, a script called Startup 
executes. The Startup file defines several variables and command aliases (alternative 
command names); this file is further described in Chapter 5. 
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A Important 


The Startup file must be in the same directory as the MPW Shell. See 
Figure 1-1, “Setup of MPW folders and files,” at the end of Chapter 1 
for an illustration of how your root MPW folder should appear, a 


Selecting commands from menus 

In MPW, commands may be built-in commands, scripts, tools, or applications, as 
explained in Chapter 1. 

Several of the built-in commands can be executed by using the File, Edit, Mark, and 
Window menus. The Project, Directory, and Build menus are optional, and are normally 
installed by UserStartup scripts. Some items in these menus execute scripts (see Chapter 3 
for details about menus). These scripts must be located in a folder with a path in the 
{Commands} variable. 

You can add your own menu items to the File, Edit, Find, Directory, and Build menus. By 
using the AddMenu command you can even add your own menus. Each user-defined menu 
item specifies a list of MPW commands that are executed when the menu item is selected. 
See the file AddMenu in the Examples folder for a number of ideas for user-defined menus. 


■ Figure 2-2 MPW menu bar with MultiFinder 

[ 6 File Edit Find Mark Window Project Directory Build B 
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Building a program: an introduction 


This section takes you step by step through the process of building a sample program. 
You’ll find that the Build menu and the Commando dialog boxes make the learning process 
intuitive and comfortable. Even if you’ve never used MPW before, you can immediately 
use the Build menus to build programs. 

MPWs automated Build menu lets you assemble, compile, and link simple programs 
without studying the command language, the numerous compiler and Linker options, or 
countless other details. You can use the Build menu to build applications, stand-alone 
code resources, desk accessories, and tools written in MPW Assembly language, MPW C, 
MPW C++, MPW Pascal, and Rez, or in a combination of these languages. You can include 
resource specifications when building programs with these menus. 


The sample programs 

In this introduction, three assembly-language programs included with MPW Assemblerare 
suggested as examples: 

■ Sample: the “Inside Macintosh” sample application 

■ Count: an MPW tool that counts characters and lines in a file (see Partn) 

■ Memory: a sample desk accessory that displays the memory available in the 
application and system heaps and on the boot disk 

Similar program examples are included with MPW C and MPW Pascal. If you are primarily 
interested in programming in one of these languages, be sure to read, in the corresponding 
language reference, the section on the example programs. If you are using a different (non- 
Apple) compiler, be sure to check its documentation for information on specific language 
versions of these examples. 

You can routinely rebuild more complex programs by selecting a single menu item. There is 
a smooth transition from the simple builds to the more complex ones. (See Chapter 8 for 
information on how to modify the Build menu and the makefile that it creates.) 
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The source files for each of these three assembly-language examples are in the 
Examples:AExamples folder that is included with the MPW Assembler distribution disks. 
For example, the source for Count consists of the files Count.a and FStubs.a. A makefile 
that contains the commands for building all of the examples is also provided in the same 
folder. Instruction files are also provided on the MPW disks for each language. If you are 
new to MPW, we recommend that you start with the tutorial that follows rather than with 
the Intructions file on the disks. At the conclusion of this tutorial you will be referred back 
to the disk instructions. 


Two easy steps 

You can build each of the example programs in two steps, using the Directory and Build 
menus: 

1. Set the current directory. 

2. Build the program. 

Both of these steps are explained next. You can use this section to take MPW on a test 
drive. 

1. Set the current directory. 

Open the Directory menu. The upper half of the menu contains the commands to show the 
current directory and to change it to an arbitrary directory. (See Figure 2-3.) The lower half 
of the menu lists frequently used directories. 


■ Figure 2-3 Directory menu 
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Select Show Directory to find out what your current directory is. You’ll see the alert shown 
in Figure 2-4. 


■ Figure 2-4 Show Directory alert 


The default directory is 


HD:MPUI: 

i oK 1 


Click OK to remove the alert. You’re going to build the assembly-language program 
Sample, so you’ll need to set the current directory to the directory that contains the 
assembly-language examples. Now open the Directory menu again and select “AExamples.” 
Selecting “AExamples” from the Directory menu runs commands that set the current 
directory. You can check to see if the current directory has been correctly reset by 
selecting the Show Directory menu item again. (The Set Directory... menu item is used to 
add other directories to the list at the bottom of the Directory menu. This menu item is 
explained in “Building a New Program” later in this chapter.) 

2. Build the program. 

Now open the Build menu, shown in Figure 2-5, and select any one of the four Build menu 
items. 

■ Figure 2-5 Build menu 
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Each Build item builds your specified program in a slightly different way: 

The program is built automatically, but only files that have 
been modified since you last built the program will be 
processed. Use this item to save time. The Command-key 
equivalent is Command-B. 


Full Build 


Show Build 
Commands 


The program is completely built, ignoring any object files or 
intermediate files that may exist from a previous build. 

The commands needed to build the program (using just those 
files affected by modifications since the last build) are 
displayed on the worksheet, but not executed. You can then 
select any or all of the commands—or modify them—and 
then press Enter to execute them. 


Show Full Build All the commands needed to completely rebuild the program 
Commands (whether modified since the last build or not) are displayed 
on the worksheet, but not executed. This is a convenient way 
to see all of the commands used in building the program 
you’ve selected. 


See “Build Menu” in Chapter 3 for more information on Build menu items. When selected, 
each Build item first displays a dialog box like that in Figure 2-6, requesting the name of’ 
your program. 


For this tutorial, select Full Build 


■ Figure 2-6 Program Name dialog box 



When the Program Name dialog box appears, type the name of the program you want to 
build (in this case, type “Sample”) and then click the OK button. (Be sure that you type 
the name Sample and not Sampler. Since you have already set the directory to 
AExamples, you don’t need to indicate that you want to build the assembly-language 
version of Sample. If you give Sampler as the program name, the Build script will 
attempt to build the source file.) 
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The Worksheet window now becomes the frontmost window. The status panel in the 
lower-left corner flashes the name of each operation as it is performed by MPW. Each of 
the MPW commands used by the Full Build script appears on the worksheet as it is 
executed. When the build has finished, your worksheet should look like Figure 2-7. 

■ Figure 2-7 Finished Sample build 

( i File Edit Find WindowMark Directory Build 



To check your work, press Enter. The Shell then executes the newly built program, 
displaying the text-edit window that Sample creates (described at the beginning of Inside 
Macintosh). When you quit the Sample program, you are returned to the Shell. 

Use the same procedure to build the two other examples in the Examples:AExamples 
folder: the tool Count and the desk accessory Memory. For guidance in using these 
examples, consult the file Instructions in the folder AExamples. 

In general, to run a newly built program, select its name (and, in the case of a tool, any 
parameters) and press Enter. If the program you have built is an application, your open 
windows, user-defined menus, and other status information will be saved before the 
program is run. When you quit the application you are returned directly to MPW with your 
previously open windows and menus still displayed. If the program is an MPW tool, it is 
run without leaving MPW (be sure to specify any required parameters and options). 

♦ Note: When MultiFinder is running, the application is simply launched in another 
partition, and the MPW Shell does not exit or go through the Suspend/Resume 
process. 
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When you build a desk accessory by using Build or Full Build, the last line of the Build 
transcript is a command that will run the Font/DA Mover to install the desk accessory in 
the System file. (Make sure there is enough memory to launch Font/DA Mover.) After this 
installation is complete, the desk accessory will appear in the Apple menu. If your 
Font/DA Mover isn’t in the directory specified by the {Commands} Shell variable, then you 
should use either the Finder, the MPW Duplicate command, or the MPW Move command, 
to move it there. 

If you’re curious about the functioning of any of the Build commands, see Chapter 8 for 
more background on the Build process. 


Building a new program 

The Directory and Build menus are convenient to use when working with your existing 
programs. You use slightly different steps for creating new programs: 

1. Set the current directory by using the Directory menu. 

2. Type your program. 

3. Select Create Build Commands from the Build menu. 

4. Select a build item from the Build menu. 

Each of these steps is explained next. 

1. Set the directory. 

The first step in creating a new program is to set the directory where you want your new 
program to reside. You can select one of the directories that appears in the Directory 
menu, or you can select another directory by using the Set Directory menu item. When you 
select Set Directory from the Directory menu, a standard file dialog box, like that in Figure 
2-8, appears. 
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Figure 2-8 Set Directory... standard file dialog box 
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Select the directory you need. After highlighting the directory you want, click Directory or - 
Select Current Directory: at the top of the dialog box. The new directory will then be 
added to the list of directories on the Directory menu. 


2. Type your program. 

The next step is to create the source files for your program. Select New in the File menu. 
(Remember that assembly-language source filenames should end with “.a”, C filenames 
with “.c”, C++ filenames with “.cp”, Pascal filenames with “.p”, and Rez filenames with 
B .r”.) An empty window now appears and you are ready to type your program. Enjoy! 

3. Select Create Build Commands from the Build menu. 

When you’ve finished typing in your program, select Create Build Commands from the 
Build menu. You’ll see the dialog box shown in Figure 2-9. 


CHAPTER 2 Getting Started 55 































Figure 2-9 CreateMake dialog box 



Type in the program’s name (without “.a”, “.c”, “xp n , or “.p” suffixes) and click a radio 
button to indicate whether you want to create an application, stand-alone code resource, 
desk accessory, or MPW tool. When you click the Files button, another dialog box 
appears, permitting you to select the needed source and library (ending with the “.o” 
suffix) files. Your program will be linked with these files. 

♦ Note: It isn’t necessary to indicate the standard library files supplied with MPW. Your 
program will be automatically linked with the appropriate libraries. The reference for 
CreateMake in Part II explains which standard library files will be used. 


The Create Build Commands command in the Build menu runs a script that creates a 
makefile with the necessary commands for building programs written in assembly 
language, C, C++, Pascal, Rez, or a combination of languages. This file is given your 
program’s name with the suffix “.make”. 


♦ Note: The Build script uses Make to determine the minimum operations necessary to 
bring the program up to date. The Build script looks for its build instructions first in 
program.make (for example, Sample.make). If no such file is found, the Build script 
looks for its instructions in MakeFile. 
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4 Select a build command from die Build menu. 

The four build commands on the Build menus are variations on a theme. (See Chapter 3 for 
an explanation of each item. A brief explanation appears earlier in this chapter under Step 
2 of Two Easy Steps.”) For now, select Full Build. The rotating beach ball cursor appears, 
indicating that processing has begun. Each step of the build process is displayed on the ' 
worksheet as it occurs. Any errors will be displayed also, making it easy to track down a 
bit of misplaced syntax. When you have fixed the problem, just select Build from the 
Build menu to quickly rebuild the program. The record of previous builds is left on the 
worksheet. 

See Part II for detailed information on each of the Build menu commands. 
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Chapter 3 Using the Shell Menus 


This chapter describes the menus and associated dialog boxes of the 
Macintosh Programmer’s Workshop 3.0 Shell. You can build simple programs by 
using the Directory, File, and Build menus. (See Chapter 2 for an easy 
demonstration.) The other menus are used for general editing. More advanced 
editing capabilities, such as scripted editing and selection specification, are 
discussed in Chapter 6. ■ 
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Features 


The MPW Shell provides the following editing features: 

■ Both menu and command-language editing. The menu commands provide the usual 
Macintosh interface. 

■ Selecting text by program syntax. You can double-click any of these paired quotation 
characters: 

() [] {} "" '• ' ' /\ 
to select everything between the character and its mate. To select text between 

»t tt i I ' ' ^ ^ 

click the left quotation character. 

■ Selection of large sections of text by embedding markers. Marked selections are 
scriptable; your command files can refer to one or more marked selections. The 
marker commands, Mark and Unmark, are available from the Mark menu. Basic 
interactive use of markers is covered later in this chapter. See Chapter 6 for more 
detailed information on scripting marked selections. 

■ Complete integration of editing functions with the command interpreter. In the MPW 
Shell, there is no separation of “command” and “editor” modes. To the Shell, text is 
text—it is only when you try to direcdy execute a string of text that the Shell decides 
whether it is a legitimate command or not. 

■ Scriptable commands. Because editing commands are part of the command language, 
you can use them with structured commands and variables to put together scripts that 
define new editing commands. (See Chapter 6.) 

■ Regular expressions for matching text patterns. These make possible powerful search- 
and-replace functions that eliminate the need to make repetitive changes by hand. 
(See Chapter 6.) 
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File format 

Shell text is saved as a text-only (TEXT) file. The file contains tab and return characters, 
but no other formatting information. This format is compatible with other applications 
that create text-only files—for example, the Shell can process MacWrite® files saved with 
the Text Only option. When you select the Open command, the Shell displays all text-only 
files in its standard file dialog box, regardless of the file creator. 


A Important From the Finder, you can open a text file created by another 

application by selecting both the MPW Shell and the text file icons, 
and then choosing the Open command, a 


You can display the invisible characters (spaces, tabs, returns, and all other “control” 
characters) with the Show Invisibles checkbox in the Format dialog box. 

A file’s tab setting, font setting, selection, window settings, auto-indent state, invisibles 
state, and markers are saved with the file in its resource fork. 


Menu commands 

In general, the menu interface is the familiar Macintosh implementation. There are a few 
differences and extensions, which are detailed in the following sections. (It’s assumed 
that you are already familiar with standard Macintosh editing techniques.) Many menu 
commands are scriptable, that is, a command-line form of the command exists (and is 
described in Part II) that lets you use the menu item noninteractively in a script. Each of 
these are indicated later in this section. 

All menu commands act on the active (that is, the frontmost) window. 


Apple menu 

Open the “About MPW” menu item to display version information. 
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File menu 


The File menu contains the Shell commands for creating, opening, printing, closing, and 
saving files. 


■ Figure 3-1 File menu 
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If the Worksheet is the current window, the menu commands Close will appear dimmed, as 
shown in Figure 3-1. If a tool is executing, all menu commands (except New and Open) 
appear dimmed. 


New 

Displays the New dialog box, shown in Figure 3-2. The MPW New dialog box allows you to 
enter a name and select a directory location for the document. The Command-key 
equivalent is Command-N. There is also a scriptable New, described in Part n. 


■ Figure 3-2 New dialog box 
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Open 

Displays an Open dialog box (similar to that in Figure 3-2) that allows you to open any 
TEXT file on the disk. When you open a file for the first time, the selection point is at the 
top of the file. When you open the file again, it reappears in the same state in which it was 
saved; that is, the previous selection or insertion point is preserved unless the file has been 
modified outside the editor. The Read Only checkbox is located just below the Open 
Document box. Check the Read-Only box to open a nonmodifiable copy of the file. The 
Command-key equivalent is Command-O. There is also a scriptable Open, described in 
Part II. 

♦ Note: If you try to open a document that’s already open in another window, that 
window will be brought to the front. Whenever you open a file, it appears in a new 
window. 


Open Selection 

If you select a document name within a window, the Open Selection command 
automatically displays the selected name. This is a useful shortcut when you have already 
displayed filenames on the screen, with the Files command, for example. You can then 
select a filename and open a file directly, bypassing the usual Open dialog box. Variable 
and command substitution occur on the selection. The Command-key equivalent is 
Command-D. 

Close 

Closes the active (frontmost) window. The Command-key equivalent is Command-W. 
There is also a scriptable Close, described in Part II. 


Save 

Saves the active window under its current name, without closing it. This menu item is 
dimmed if the contents of the window haven’t been modified since it was last saved. The 
Command-key equivalent is Command-S. There is also a scriptable Save, described in 
Part II. 
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Save As 


Displays a Save As dialog box, allowing you to change the name and directory location of 
the active window. Saves the current contents of the window as the Save As file, and 
allows you to continue editing the new file. The old file is closed without saving, under its 
original name. 

Save a Copy 

Saves the current state of the active window to a new file on the disk. You can then 
continue editing the old file. 

Revert to Saved 

Throws away any changes you have made since you last saved the active window. This 
menu command is dimmed if the window has not been modified since you last saved. 
There is also a scriptable Revert, described in Part EL 

Page Setup 

Displays the standard Page Setup dialog box. 

Print Window/Print Selection 

Prints either the entire contents of the active window or the selection in the active 
window. If any text is selected in the active window, that text is printed. If no text is 
selected, the entire contents of the window (that is, the entire file) are printed. 


♦ Note: For the Print command to work properly, you must install the printer drivers 
available on the latest version of the Printer Installation disk. Use the Chooser Desk 
Accessory from the Apple menu to specify which printer to use. Use the Page Setup 
dialog box to specify paper size, orientation, and reductions or enlargements. 
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The Print menu item doesn’t display the usual Print dialog box. Instead, you can specify 
printing parameters by setting the Shell variable {PrintOptions}, described in Chapter 5. 
Printing options include 

■ the number of copies to print 

■ which pages to print 

■ print quality 

■ font 

■ font size 

■ headings 

■ title 

■ borders 

■ printing the pages ip reverse order (for use with the LaserWriter) 

See the description of the Print command in Part II for a complete specification of these 
options, or enter the command Help Print to see a summary. 


♦ How Print works 

The Print Window menu item executes the Shell command 
Print {PrintOptions} "{Active}" >> "{Worksheet}" 

Print Selection executes the same command with .§ added after the name of the 
active window. ♦ 


Quit 

Quit returns you to the Finder, first allowing you to save all open files. The Command-key 
equivalent is Command-Q. There is also a scriptable Quit, described in Part II. 
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Edit menu 

In addition to the usual Macintosh editing commands, the MPW Edit menu (Figure 3-3) 
contains a few special menu items. See “Editing With the Command language” in Chapter 
5 for more information on using the scriptable forms of the commands on this menu. 


■ Figure 3-3 Edit menu 
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Undo 

Undoes the most recent changes to text in the active window (but not changes to resources 
such as font or tab settings). You can select Undo again to redo changes. The Command- 
key equivalent is Command-Z. There is also a scriptable Undo, described in Part II. 


Cut 

Copies the current selection in the active window to the Clipboard and then deletes it 
from its original location. The Command-key equivalent is Command-X. There is also a 
scriptable Cut, described in Part II. 


Copy 

Copies the current selection in the active window to the Clipboard. The Command-key 
equivalent is Command-C. There is also a scriptable Copy, described in Part II. 
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Paste 


Replaces the contents of the current selection in the active window with the contents of 
the Clipboard. The Command-key equivalent is Command-V. There is also a scriptable 
Paste, described in Part II. 


Clear 

Deletes the current selection in the active window. There is also a scriptable Clear, 
described in Part n. The keyboard equivalent is the Clear key. 


Select All 

Selects the entire contents of the active window. The Command-key equivalent is 
Command-A. 

Show Clipboard 

Opens a window displaying the contents of the Clipboard, if any. 

Format 

Displays the Format dialog box offering a selection of fonts and sizes. The Command-key 
equivalent is Command-Y. This dialog box is shown in Figure 3-4. There is also a scriptable 
Format, described in Part II. 

■ Figure 3-4 Dialog box of the Format menu item 
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♦ Note: Selecting a font and font size affects the entire active window, not just the 
current selection in that window. 
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Tabs 


Sets the number of spaces that a tab character will signify for the 
active window. 

You can set the default format for a new window by using the Shell 
variables {Font}, {FontSizel, {Tab}, and {Autoindent}. These are 
described in Chapter 5. 

Auto Indent Toggles Auto Indent on and off. When Auto Indent is on, pressing 
Return lines up text with the previous line. (A check mark indicates 
that Auto Indent is on.) 


Temporary disable feature: To temporarily disable Auto Indent for one line, press Option- 
Return. That line will begin flush left. 


Show Invisibles Displays these invisible characters: 

Tab A 

Space 0 

Return -i 

All other control characters i 

The MPW Shell editor ignores any zero-width characters (that is, control 

characters that do not have a character bitmap) typed from the keyboard. 
(Usually these are typed by accident.) If you really want a control character in 
your document, you can enter it in the Key Caps desk accessory and then paste it 
in your document To delete control characters that might not be visible, select 
Show Invisibles from the Format dialog box. 

The rest of the dialog box consists of a selection of the fonts installed in your System file. 

Available font sizes are displayed in the dialog window. 


Align 

Aligns the currently selected text with the top line of the selection. 

Shift Left, Shift Right 

These commands move the selected text left or right by one tab stop. You can thus move 
a block of text while maintaining indentation. 
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Shift Left Removes a tab from the beginning of each line. The Command-key 

equivalent is Command-!. 

Shift Right Adds a tab, or the equivalent number of spaces, to the beginning of 
each line. The Command-key equivalent is Command-]. 

If you hold down the Shift key while using these menu items, the selection will be shifted 
by one space, rather than by one tab. 


Find menu 

The Find menu contains the routine commands for searching and replacing text. Each of 
the items in the Find menu is described below. 


■ Figure 3*5 Find menu 
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Find 

Displays a Find dialog box and finds the string you specify. By default, the Shell editor 
searches forward from the current selection in the active window (and does not wrap 
around). The Command-key equivalent is Command-F. This dialog box is very similar to 
the Find-and-Replace dialog box described under Figure 3-6; that explanation of the radio 
controls and check boxes applies to both dialog boxes. There is also a scriptable Find, 
described in Part II. 
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Repeats the last Find operation, on the active window. The Command-key equivalent is 
Command-G. 


Find Selection 

e current selection in the active window. The Command- 



Display Selection 

Scrolls the current selection in the active window into view. 

Replace 

Displays the Find-and-Replace dialog box shown in Figure 3-6 and explained there. The 
Command-key equivalent is Command-R. 


Replace Same 

Repeats the last Replace operation. The Command-key equivalent is Command-T. 
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Figure 3-6 Dialog box of the Replace menu item 
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The operation of this dialog box is very similar to that of the Find dialog box, except that 
selected strings can be located and replaced with a different string throughout a file. Both 
the Find and the Replace dialog boxes have three radio buttons, offering you one of three 
options: 


Literal 
Entire Word 


Selection 

Expression 


Finds the exact string that you specify, wherever it may 
appear, even if it is part of other words or expressions. 

Finds the specified string only when it occurs as a single woid. 
To the editor, a word is composed of the characters a-z, A-Z, 
0-9, and the underscore character (_). (You can change these’ 
default values by redefining the Shell variable {WordSet}—see 
“Predefined Variables” in Chapter 5.) 

Enables the full selection and regular expression syntax, as used 
with the command language and described in Chapter 6. These 
expressions allow powerful selection and pattern-matching 
capabilities that use a special set of metacharacters 
introduced later in this section. 


Any combination of these three check boxes may be selec ted : 

Case Sensitive Searching is normally case insensitive; selecting this checkbox 
specifies case-sensitive searching. 

Search Backwards Search backward from the current selection to the be ginnin g 
of the file. (Normally, searching is forward and stops at the end 
of the file.) 

Wrap-Around Searches forward to the end of file, then wraps around and 

Search searches from the beginning of the file to the cursor's 

location when the search was initiated. (The direction of 
Search is reversed if Search Backward is also selected.) 
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These dialog options set the Shell variables {CaseSensitive}, {SearchBackward}, 
{SearchWrap}, and {SearchType}. You an also use these variables in scripts to set the 
related options in the dialog boxes. See “Variables Defined in the Startup File” in 
Chapter 5. 

For Find and Find-and-Replace operations, a beep indicates that the string was not 
found. 


♦ Hints on using Find 

You can reverse the direction of a current search operation by pressing Shift as 
you select the menu item or click the OK button. The direction is changed for 
the current search operation only; the settings of the dialog's check box and 
the {SearchBackward} variable are not affected. 

For example, if you are in the middle of a file and you want something above 
the current cursor position, then hold down the Shift key as you click OK. The 
search will then proceed backward through the first part of the file. 

You might also use the Shift key to make sure that you've found all instances 
of an item from an arbitrary position in the window. Press Command-G to run 
Find Same forward. Press Shift-Command-G to run Find Same backward. ♦ 


Selection expression 

When the Find-and-Replace dialog box’s “Selection Expression” switch is selected, you 
can use a special set of expression operators to specify selections and text patterns. This 
section introduces a commonly used subset of these selection operators. Many more 
capabilities are available. A full discussion of them can be found in Chapter 6. 

Selection by line number: A number given by itself specifies a line number. In Figure 3-7, 
for example, the command selects line 30 in the active window. 

■ Figure 3-7 Selection by line number 
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Wildcard operators: The same wildcard operators used in filename generation can also 
be used to specify text patterns for Find commands: 

? Any single character (other than Return). 

* Any string of 0 or more characters, that does not contain a 

Return. (To get the = character, press Option-X.) 

[i characterList ] Any character in the list. 

Note: The brackets must be typed; they don’t indicate an 
optional syntax element. 

[-characterList] Any character not in the list. (To get the character, press 
Option-L.) 

These pattern-matching operators are part of a larger set called regular expression 
operators, used to define searches and other scripted operations. A regular expression 
consists of literal characters and/or regular expression operators, and it must be enclosed 
in slashes (/.../). Figure 3-8 shows an example. 


■ Figure 3-8 Example of a regular expression 
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The command shown in Figure 3-8 finds and selects any string that begins with “init” and is 
followed by any characters other than a return or a space. Figure 3-9 shows the result of this 
command. 


■ Figure 3-9 Text selected with the Find command 
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As mentioned, many additional Find-and-Replace capabilities are available. (See 
Chapter 6.) In the command language, the Find-and-Replace functions are performed by 
the Find-and-Replace commands. There’s also a tool named Search (described in Part II) 
that can search through a list of files for the occurrence of any text pattern. 


Mark menu 

A marker is a text selection that has been given a name. Markers are useful for navigating 
within a window, and they can simplify many selection expressions. The upper part of the 
Mark menu contains the commands Mark and Unmark and the lower part lists all existing 
markers. (By the way, when you first start MPW 3.0, you’ll notice that this area of the Mark 
menu contains a list of MPW commands that have been marked in order to display them 
conveniently in a menu. You can unmark them if you prefer.) To jump to the location of a 
marker, you simply choose the name of the marker you want from the Mark menu, shown 
in Figure 3-10. 
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Markers can be created and used both interactively, via the Mark menu, and 
programmatically, via the Shell commands Mark, Unmark, and Markers. For a detailed 
discussion of the syntax, characteristics, and programmatic use of markers, see Chapter 6 
and Partn. 

■ Figure 3-10 Mark menu 
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To create a new marker interactively, first select the text you want to mark, then choose 
“Mark” from the Mark menu. A dialog box like that in Figure 3-11 appears, asking for the 
name you want the marker to have. The editable text field in the Mark dialog box is 
initialized to the first word (that is, whatever you would select by a double click) in the 
selection. If you click Cancel in the dialog box, the selection is unchanged and no new 
marker is created. If you click OK, a new marker is created with the specified name and 
the new marker's name is added to the list of marker names displayed by the Mark menu. 


■ Figure 3-11 Mark dialog box 
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If you try to create a new marker using the name of an already existing marker, a dialog 
box will appear, giving you the chance either to delete the old marker and add the new 
(OK), or to forget about adding the new marker (Cancel). 


♦ Hints on using Mark 

Markers are very handy for quick navigation through source files. You may 
want to mark important data declarations and all procedures so that you can 
quickly jump to any procedure by selecting its marker. Markers are listed 
according to their position in the file. ♦ 


Unmark 

If you choose the Unmark menu item from the Mark menu, you’ll see a dialog box (Figure 
3-12) that contains a list of currendy defined markers and the two buttons Delete and 
Cancel. If a marker is currendy selected, its name is highlighted in the marker list. You can 
select any number of marker names from the list If you click Delete, every marker 
selected in the list is deleted. If you click Cancel, the selection remains unchanged and no 
markers are deleted. 

■ Figure 3-12 Unmark dialog box 
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Window menu 


The upper portion of the Window menu contains the two commands Tile Windows and 
Stack Windows; the middle area lists all open windows, as shown in Figure 3-13- The lower 
area of the Window menu lists any open Projector windows. 

■ Figure 3-13 Window menu 
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Tile Windows 

Use this command to arrange windows in a tile pattern on the screen so that each window’s 
contents are visible. To include the Worksheet in the tiling, press the Option key as you 
select Tile Windows. 

Stack Windows 

Use this command to arrange windows in a diagonally staggered pattern on your screen. 
This is the “open file folder” way to see several windows at once. To include the 
Worksheet in the stacking, press the Option key as you select Stack Windows. 

Customizing window commands 

The Tile Windows and Stack Windows menu commands execute the Shell commands: 

TileWindows {TileOptions} >> "{Worksheet}" 

StackWindows {StackOptions} >> "{Worksheet}" 

You may customize the operations of tiling and stacking by using the Shell variables 
{TileOptions} and {StackOptions}. Options include 

■ which windows to tile 

■ including the Worksheet (without pressing the Option key) 

■ horizontal or vertical tiling 

■ spacing between stacked windows 

■ specifying a rectangle in which to tile or stack windows 
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List of open windows 

The remainder of the menu lists all open windows in the order in which they were opened, 
The full pathname is listed. To bring any window to the front, select that window from the 
list. 

Selecting a window from the menu brings that window to the front, that is, superimposes 
it over anything else on your display. A check indicates that the window is currently the 
“active” window, that is, the frontmost. A bullet (•) indicates that the window is die 
“target” window, that is, the second to the front. Underlining indicates that a window 
contains changes that have not yet been saved. 


Project menu 

The Project menu, shown in Figure 3-14, puts three of the most often used Projector 
commands at your fingertips. Of course, you can modify this menu to add the rest of 
Projector’s commands or eliminate the menu altogether if you don’t use it. 

The three menu items on the Project menu are briefly described here. For an introducdon 
to the basics of using these functions, see “Projector Windows” in Chapter 4. For a 
detailed explanation of the MPW project-management system, see Chapter 7. 


■ Figure 3-14 Project menu 
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New Project 

The New Project dialog box appears as shown in Figure 3-15. Use this dialog box to create 
a unique new project or subproject. You can use the Comment text frame to briefly 
explain the purpose of the project or subproject. Projector automatically adds your user 
name as the project’s creator. 
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Figure 3-15 New Project dialog box 



Checkin 

The Check In dialog box appears as shown in Figure 3-16. After checking out and 
modifying a file, you will routinely use this dialog box to check the file back in to 
Projector. 

■ Figure 3-16 Check In dialog 



Click the Question Mark button to display information about the project, a project file, 
or a specific revision of a project file. See Chapter 7 for more information. 
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Check Out 

The Check Out dialog box appears as shown in Figure 3-17. You’ll routinely use this dialog 
box to select a project for use and then to check out a project file you want to modify. 
The date, time, and user name of the checked-out file are recorded; no one else can 
modify the same revision of a file at the same time. 

■ Figure 3-17 Check Out dialog box 



Click the Question Mark button to display information about the project, a project file, 
or a specific revision of a project file. See Chapter 7 for more information. 


Directory menu 

The Directory menu, shown in Figure 3-18, lets you display and easily change the default 
(current) directory. The Directory menu is implemented by the scripts DirectoryMenu and 
SetDirectory, which you can modify to suit your own needs. 
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Figure 3-18 Directory menu 
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Show Directory 

An alert box displays the name of the current default directory. 

Set Directory 

When you select this menu command the Set Directory dialog box (Figure 3-19) appears, 
providing interactive selection of the default directory. Your selection is then added to 
the Directory menu. 


■ Figure 3-19 Dialog box of the Set Directory menu item 



list of directory names 

Selecting a directory name makes this directory the new default directory. 
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As you select various default directories, using either the Set Directory menu command or 
the SetDirectory command, each is added as a separate menu command to make it easy 
to return to that directory in the future. The UserStartup script creates menu items for 
each of the Examples folders in the MPW directory, and for the default directory at the 
time the UserStartup script is run. You can add your own favorite directories by modifying 
UserStartup. 

A 'Warning Directory names should not contain any of these special characters: 

; A ! < / ( 

These characters have special meanings when they appear 
as menu items. ▲ 


Build menu 

The Build menu, shown in Figure 3-20, has two primary purposes. The fust purpose of the 
Build menu is to create a makefile containing the commands needed to build a program. 
The command Create Build Commands, which is listed first on the menu, creates the 
makefile pr 0 gram.w 2 .ke (using the name of your program). If you have not used this 
command—that is, if program .make does not exist—then MPW uses the file Makefile. 

The second purpose of the Build menu is either to build a specified program or to display 
the commands needed to do the build. When you select one of the r emaining commands 
on the menu—Build, Full Build, Show Build, and Show Full Build Co mmands — a dialog box 
appears asking for the name of the program that you want to build. 

Use of the Build menu is demonstrated in Chapter 2, “Building a Program: An 
Introduction.” 


■ Figure 3-20 Build menu 


Create Build Commands. 


Build... 3SB 

Full Build... 

Shorn Build Commands... 
Shorn Full Build Commands... 


CHAPTER 3 Using the Shell Menus 83 













Create Build Commands 

Use this item to create a makefile containing the build commands for a specified 
program. When you click Create Build Commands, the CreateMake dialog box appears. 
(See Figure 3-21.) You can then enter the program name and select its type (that is, 
Application, Tool, or Desk Accessory). Make sure that you do not include any of the 
following four suffixes to the program name: 

.a .c .p .cp 

Click the Files button to select the program’s source and library files. (MPW libraries are 
automatically linked; certain special libraries you may require might not be automatically 
linked. See CreateMake in Part II.) If the program’s name is program, a new makefile, 
called “program.mke”, is created. The makefile will contain simple build commands from 
the program. (See Chapter 9 for more information on Make.) 

Be sure to run Create Build Commands whenever you create additional source or library 
files for a program. Answering the CreateMake dialog box generates a new set of rules in 
programsrake that includes the new source files. 


■ Figure 3-21 CreateMake dialog box 
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When you select one of the following four Build items from the Build menu, a dialog box 
appears (as shown in Figure 3-22), asking for the name of the program you want to build. 
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■ Figure 3-22 Program Name dialog box 
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Type the name and click OK. The build option you have selected will proceed, displaying 
on the Worksheet each command needed to build the program as it is used, along with any 
error messages. Each of these four Build menu items uses the MPW tool Make to 
determine which operations are necessary to build the program. 

Build 

The program is built automatically, but only files that have been modified since you last 
built the program will be compiled. Use this item to save time. The Command-key 
equivalent is Command-B. 

Full Build 

The program is completely built, ignoring any object files or intermediate files that may 
exist from a previous build. 

Show Build Commands 

The commands needed to build the program (for just those files affected by 
modifications since the last build) are displayed on the worksheet, but not executed. You 
can then select any or all of the commands—or modify them—and press Enter to execute 
them. 

Show Full Build Commands 

All the commands needed to completely rebuild the program (whether modified since the 
last build or not) are displayed on the worksheet, but not executed. This is a convenient 
way to see all of the commands used in building the program you’ve selected. 

The Makefile a program.makt” is created by the Create Build Commands menu item 
(described previously in this chapter). If you have not used this item—that is, if 
pr 0 gram.m 2 .ke doesn’t exist—MPW will use the file MakeFile. 


CHAPTER 3 Using the Shell Menus 85 

















User-defined menus 


You can define your own menu commands with the AddMenu command, described at the 
end of Chapter 5. These commands can be appended to existing menus, or you can create 
new menus. In fact, the Projector, Directory, and Build menus have been created by using 
AddMenu. You may add to, change, or delete these menus to suit your individual needs. 
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Chapter 4 Using MPW: The Basics 


This chapter introduces the basic conventions for manipulating files, 
editing text, executing commands, and responding to dialogs in MPW 3.0. You 
can easily enter all commands, command options, and parameters by using the 
menus and dialogs. The basics for directly typing commands in any window are 
also introduced. A full discussion of command scripting can be found in Chapter 
5. For an introduction to building a simple program, using examples contained in 
the Examples folder, see Chapter 2. Chapter 3 introduces the menus and their 
contents. Chapter 7 presents the dialogs and complete information on Projector, 
the project management system. ■ 
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Editing 

Basic editing functions are available as menu commands. You can open a file by using the 
Open command, or by selecting its name on the screen and choosing the Open Selection 
command (Command-D) from the File menu. You can select and edit text with the usual 
Macintosh editing techniques, using menu commands to cut, copy, and paste selected 
text. The menu commands are described in Chapter 3. 

You enter and edit command lines in a window exactly the same way you enter plain text 
You can select any stretch of text and press Enter to send the selection to MPWs 
command interpreter for execution. 

Editing with MPW is unique in that most menu functions are duplicated in the Shell 
command language. Editing and other command-language functions are fully integrated— 
you enter and execute editing commands just like any other commands. Editing 
commands are entered in the active window (the frontmost window), but they act on 
text in the target window (the second window from the front), or another window that 
you explicitly name. The command language lets you produce scripts of editing 
commands: You can save any series of commands as a normal text file and execute the file 
by simply entering the filename. Command-language editing is discussed further in 
“Editing With the Command Language” in Chapter 5. 

For an explanation of selections, markers, and pattern matching with regular expressions, 
see Chapter 6, “Advanced Editing.” 


Entering commands 

All MPW commands and their options can be selected from menus and dialog boxes. 
Generally, this interactive method of command selection is the easiest You can 
immediately execute commands selected from menus and dialog boxes, or you can use 
the dialog boxes to compose complex command lines that can then be copied to a script. 
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The dialog boxes for MPW commands are generated by the Commando user interface 
(described in the last section of this chapter). Besides the usual Macintosh dialog boxes, 
Commando provides several new forms and controls to handle the special requirements of 
MPW tools. For example, dialogs for commands with many options may have several 
nested dialog boxes. Which dialog boxes are actually displayed may vary according to 
dependency relations between the particular options you may have selected. Some of the 
specialized dialog controls are introduced at the end of this chapter. Other unique dialog 
boxes are shown in Part II of this reference, with their respective commands. A detailed 
discussion of all the elements of Commando dialogs can be found in Chapter 13, which 
explains how to create a Commando interface for your own tools and scripts. 

Of course, you can always type commands directly in any window as a series of words 
separated by spaces or tabs. (See below.) 


Typing commands in a window 

By default, command output and any error messages appear in the window immediately 
below the executed command line. Commands are not case sensitive. You can have 
multiple open files, and you can enter commands in any window. 

The simplest commands consist of the command name only. For example, type the 
command 

Date 

and press the Enter key (without pressing Return first—that is, the insertion point must be 
on the samp line as the command when you press Enter). This command outputs the date 
and time: 

Tuesday, January 15, 1989 7:12:00 AM 
Commands can have options. For example, 

Date -d 

The -d option tells the Date command to list the date only, 

Tuesday, January 15, 1989 

Commands typed into an open file are referred to as standard input Output produced 
by most commands is sent to an open file called standard output, which is normally 
connected to the window in which the command was entered. Any window that is used to 
enter standard input and display standard output is referred to as the console. 
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Most commands read from standard input, write their output to standard output, and 
write error messages to diagnostic output. By default, standard input refers to text that is 
selected and entered while the tool is running. Standard output and diagnostic output 
appear following the commands. (These input and output defaults can be changed using 
I/O redirection. See Chapter 5 for details.) 


♦ Using the Alias command 

You may get tired of typing the entire command name for frequently used 
commands such as Directory. However, you can easily define your own 
alternative names with the Alias command. For example, after executing this 
command. 

Alias dir Directory 

you can execute the Directory command by entering the new command 
name: 

dir 

To make an alias definition part of the Shell's standard startup procedure, place 
the definition in the file UserStartup. See Chapter 5, “The Startup and 
UserStartup Files.” ♦ 


The Enter key 

The Enter key serves as a “do it” button, causing commands to be executed. You can type 
commands in any window and press the Enter key to execute the command line. You can 
also select command text that is already on the screen and press the Enter key to execute 
the selected text. Clicking on the status panel, located at the lower left of a window, has 
the same effect as pressing the Enter key. Pressing Command-Return also has the same 
effect as presing the Enter key. 

A Important When no text is selected, the entire line is executed the moment the 
Enter key is pressed, regardless of where the insertion point is on the 
line, a 
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Executing several commands at once 

By selecting several lines of command text and then pressing Enter, you can execute any 
number of commands with one stroke. An example is shown in Figure 4-1. 


■ Figure 4-1 Pressing Enter to execute selected text 



In Figure 4-1, executing the selected text would First make a new folder (directory) named 
Backup, then copy the files Startup and UseiStartup into Backup, and then list all of the 
files in Backup. (Each of these commands, and the pathname syntax, is described in the 
sections that follow.) 

You can also directly execute text files that contain other commands simply by entering 
the filename of the script. Executing a script has the same effect as selecting the 
commands in an open window and pressing Enter—the only difference is the scope of 
variable and alias definitions (discussed in Chapter 5). 


Terminating a command 

To terminate a command while it’s executing, press Command-period, the standard 
Macintosh command for this purpose. 
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A Important Many commands (including Asm, C, and Pascal) normally take their 
input from a file; however, if no file is specified, they will begin 
reading from the console (that is, from the window where the 
command was entered: “standard input”). If the Shell appears not to 
be listening to the commands you are entering, it probably isn’t: The 
currently executing command (shown in the active window’s status 
panel) may be reading the text that you enter. If a program is reading 
from standard input, you can press Command-Enter (or Command- 
Shift-Return) to indicate end-of-file and terminate input. (See 
“Terminating Input With Command-Enter” in Chapter 5.) a 


The Help command 


The Help command displays summary information for commands. For example, to display 
a description of the Files (list files) command and its options, type the command 


Help Files 

and press the Enter key. You’ll see the following syntax description: 


Files [option...] 
—c creator 
-d 
-f 
-i 
-1 

-m columns 

-n 

-o 

-q 

-r 

-s 

-t type 
-x format 


[name...] > fileList 

# list only files with this creator 

# list only directories 

# list full pathnames 

# treat all arguments as files 

# long format (type, creator, size, dates, etc.) 

# n column format, where n = columns 

# don’t print header in long or extended format 

# omit directory headers 

# don’t quote filenames with special characters 

# recursively list subdirectories 

# suppress the listing of directories 

# list only files of this type 

# extended format—fields specified by format 
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Note: The following characters can specify the format 
a Flag attributes 

b Logical size, in bytes, of the datafork 

r Logical size, in bytes, of the resource fork 

c Creator of File ("Fldr" for folders) 
d Creation date 

k Physical size, in kilobytes, of both forks 

m Modification date 

t Type 

o Owner (only for folders on a file server) 

g Group (only for folders on a file server) 

p Privileges (only for folders on a file server) 

♦ Note: In Help texts, the brackets are a syntax element indicating that a parameter is 
optional. An ellipsis (...) indicates that the preceding item may be repeated. (Note 
that this use of the ellipsis is a syntax convention only for Help text and 
documentation; an ellipsis character (Option-Semicolon) in an actual command line 
invokes the command’s Commando dialog.) See the section “Syntax Notation” at the 
end of the Introduction to this reference. The number sign (#) is the MPW comment 
character. 

You can directly edit and execute the text on the screen. For example, assuming that your 
current directory is {MPW}, you can edit the above text as follows: 

1. Use the mouse to select [ option... ] and [ name... ]; replace them with 
the option -1 and the directory name Scripts. 

2. Remove the output specification > fileList. 

The result is a command that will list the files in directory Scripts, in long format: 

Files -1 Scripts 

(Scripts is the directory containing various MPW scripts; the -1 option generates “long” 
output.) Press Enter to execute the command. Directory information appears 
immediately following the command. 

You can also use the Help command to display additional summary information, including 

■ an annotated list of all MPW commands 

■ an annotated list of the characters that have special meanings to the MPW Shell 

■ descriptions of the syntax of expressions, selections, and text patterns 

■ a summary of MPW Shell shortcuts 

■ a summary of predefined MPW Shell variables 

■ a summary of Projector, the project management system 
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For general information about Help, execute the Help command with no parameters: 
Help 

This command displays the information shown in Figure 4-2. 


■ Figure 4-2 Help summaries 



You can directly execute the Help commands given in the “Help Summaries” list 


♦ Note: The MPW Help file should be in the same directory as the MPW Shell or in the 
System folder. 


File-management commands 

The MPW Shell lets you manipulate files without returning to the Finder. Table 4-1 
introduces the most commonly used file-management commands. 


♦ Note: The descriptions in the table omit some of the command options that are 
available. For complete descriptions, see Part II. 
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■ Table 4-1 Basic file-management commands 


Command Description 


Backup [option] -from folder -to folder [file..] 

Copy files in source folder to destination folder 
based on modification date. This is useful when you 
maintain an identical backup folder on a separate 
disk. 


Catenate [file... ] 

Read the data fork of each file and write it to 
standard output. (By default, standard output is to 
the active window, immediately after the 
command.) 

Close [ option ] [-a 1 window...] 

Close windows. 

Delete name... 

Delete file or directory name. If name is a directory, 
all of its contents are deleted. 

Directory directory 

Set the default directory to directory. Directory 
with no parameters writes the pathname of the 
current directory. 

Duplicate name... targetName 

Duplicate file or directory name to file or directory 
targetName. 

Exists name... 

Determine the existence of file or directory name. 

Files [name...] 

List names of directories and files. Options allow 
you to include various attributes in the listing. 

GetFileName [option..] [pathname] 

Display a standard file dialog box. 

Mount drive... 

Mount volumes. 

Move name... targetName 

Move file or directory name to targetName. 

New [name...] 

Open a new window. 

Newer [option..] name... target 

Compare modification dates between files name 
and target. List files newer than target. 

NewFolder name... 

Create the new directory name. 

Open [option] [names...] 

Open a window. 

Rename namel name2 

Rename File or Directory namel to name2. 

Revert 

Revert window to previous saved state. 

Save [-a 1 window...] 

Save windows. 

SetDirectory directory 

Set the default directory. 

SetFile [option... ]file... 

Set file attributes. 


(Continued) 
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■ Table 4-1 (Continued) Basic file-management commands 


Command 

Description 

SetPrivilege [option..] folder... 

Set access privileges for folders on the file server. 

SetVersion [option ... ] file 

Independently maintain the version and revision 
numbers as a resource in the application or tool. 

Optionally, update a version and revision string in a 
source file. 

Target name 

Make a window the target window. 

Volumes [name... ] 

List mounted volumes. 

Wherels [option... ]pattern 

Find all files that have a partial pathname pattern, in 
any level of any directories. 

Which [command] 

Determine, for the specified command, which 
existing aliases, Shell built-in commands, and 
commands accessed via the Shell variable 
[Command^ will be executed when command is 
entered. 

Windows 

List open windows. 


File and window names 


In the MPW, files and windows are specified in the same way. When a name is passed as a 
parameter to a command, the system looks first for an open window with that name; if no 
window is found, it looks for a file on the disk. 

The following rules apply to naming: 

■ Names are not case sensitive. 

■ A single component (file or directory name) of an HFS pathname is limited to 31 
characters. 

■ Any character except a colon (:) may be used in a file or directory name. (Colons 
separate elements in a pathname.) 
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It’s best to avoid using spaces and special characters in filenames. When using filenames 
that contain spaces, you’ll need to quote them so that they won’t be interpreted as 
individual words in the command language—for example, you would need to specify the 
name “System Folder” as follows: 

Files "HD:System Folder" 

For the rules concerning quoting, see “Quoting Special Characters” in Chapter 5. 


Selection specifications 

Commands that take filenames for parameters can also act on the current selection in a 
window. The current selection character, § (Option-6), represents the currently selected 
text in a window. There are two ways to use this character: 

§ Cunendy selected text in the target window. (The target window is the 

second window from the front, as explained in Chapter 1.) 

name.% Currendy selected text in window name. 

For example, the Count command counts lines and/or characters in a file. The command 

Count -1 Sample.a.§ 

counts the lines within the current selection in the window Sample.a. 

The current selection is explained more fully in “Editing With the Command Language” in 
Chapter 5. 

♦ Note: The MPW Shell uses a number of special characters (like §) from the extended 
character set. These characters are fully listed in Appendix C. 


Directories and pathnames 

With the hierarchical file system (HFS), specifying a filename alone is often not enough to 
identify a file—you frequendy need to specify a pathname. (See Figure 4-3 for a sample 
HFS structure.) A full pathname is specified as follows: 

volume : [directory :...] filename 
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A full pathname contains at least one colon (:), but cannot begin with a colon. An example 
of a full pathname is 

"HD:MPW:MPW Shell" 

(The quotation marks are required because the filename “MPW Shell” contains a space.) 


■ Figure 4-3 Hierarchical directory structure 
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A partial pathname is usually all you’ll need to specify. When HFS encounters a partial 
pathname, it begins the path at the current default directory. Any name that contains no 
colons or begins with a colon is considered a partial pathname. A partial pathname that 
contains no colons is a leafname. For example, the name 

:AExamples 

is taken as a partial pathname. However, the name 

MPW: 

is taken to be a full pathname (that is, a volume name only), rather than meaning the 
directory HD:MPW. (When in doubt, you can always specify the full pathname for a file or 
command.) 
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Double colons (::) in a pathname specify the current directory’s parent directory; triple 
colons specify the “grandparent” directory (two levels up), and so on. See the chapter 
“File Manager” in Volume IV of Inside Macintosh for more information on HFS 
conventions. 


♦ Note: Notice that there’s no single “root” directory—each volume name (that is, disk 
name) is a separate starting point for a directory tree. 


You can use the Files command to list the names of files and directories. For example, the 
command 

Files HD:MPW: 

might display the following: 

:Examples: 

:Interfaces: 

:Libraries: 

:ROM Maps: 

:Scripts: 

:Tools: 

'MPW Shell* 

MPW.Help 

Quit 

Resume 

Startup 

Suspend 

SysErrs.Err 

UserStartup 

Worksheet 

...and so on 

In the output of the Files command, the names that begin and end with colons are 
directory names, and the other names are filenames. All of these names are partial 
pathnames—in this case, “HD:MPW” forms the beginning of each pathname. Also note 
that filenames containing special characters are quoted. 
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Command search path 

When you enter a command name (that is, a leafname), the Shell searches for the 
command in the directories listed in the Shell variable {Commands}. As described in 
Chapter 5, this search path is initially set to 

:(the current directory) 

HD:MPW:Tools:, 

HD:MPW:Scripts:, 

HD:MPW:Applications:, 

This means that when you type any command the Shell first assumes that you want to 
execute a tool; if it can’t find the tool, it then assumes that you want a script; if it can’t 
find the script, it then assumes that you want an application. If your frequency of use is 
different, you can change the search path to improve the Shell’s performance. (See 
Chapter 5.) 


Changing directories 

You can change the default directory with the Directory command. Assuming you have a 
hard disk named HD, you could change the default directory to the directory Examples in 
the MPW folder with the command 

Directory HD:MPW:Examples 

Like most commands, Directory runs silently—that is, it generates output only if an error 
occurs. To verify that you have set the appropriate directory, enter the Directory 
command with no parameters: 

Directory 

This command displays the current or default directory. 

Remember that to specify a pathname containing spaces or other special characters, you 
must surround it with single or double quotation marks. (See Chapter 5 for rules on 
quotation.) 

If you specify a directory whose name is a leafname, the Directory command searches the 
directories listed in the Shell variable {DirectoryPathj. If the variable is undefined, then 
the command looks in the current directory. 
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♦ Using the {DirectoryPath} 

Here’s an easy way to move quickly between directories on different branches. 
Suppose you have a directory structure like that shown in Figure 4-3, with a 
DirectoryPath of 
,HD:MPW:" 

Now, if you happened to be in the System folder, you could set your directory to 
Tools with this command: 

directory Tools 

Because this command specifies only a leafname, the Tools directory is looked 
for first in (where it is not found) and then in HD:MPW (where it is found). 
The directory is then set to HD:MPW:Tools. ♦ 


Pathname variables 

One way of specifying a pathname is by using Shell variables. For example, the Shell 
variable {MPW}, defined in the Startup file, expands to form the full pathname for the 
MPW folder, in this case “HD:MPW:” (assuming that the MPW folder is at the top level). 
Thus, the Directory command could be entered as 

Directory "{MPW}Examples” 

In this particular case, the quotation marks aren’t necessary. If you adopt the practice of 
never using spaces or other special characters in a pathname, you don’t need to bother 
with quotation marks. On the other hand, if you sometimes use spaces or other special 
characters in a pathname, it would be a good idea to use quotation marks whenever 
variables are included in a pathname. 

You can use the Set command to define and redefine variables, as described in Chapter 5. 
To see the values of all currendy defined variables, enter the Set command with no 
parameters: 

Set 
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Wildcards (filename generation) 

You can specify a number of files at once by using the wildcard characters ? and * 
(Option-x). The ? character matches any single character (except a colon or Return); » 
matches any string of zero or more characters (other than colon or Return). For example, 
the command 

Files a 

lists all filenames in the current directory that end with the suffix “.a”. (Several other 
wildcard characters can also be used to generate filenames—see “Filename Generation” in 
Chapter 5.) 


Locked and read-only files 

If you open a file that is locked, or located on a locked disk, the status panel displays a 
lock icon, as shown in Figure 4-4. When you open a read-only file, the status panel displays 
a read-only icon, as shown in Figure 4-5. No editing or command execution is allowed in 
these windows. 


■ Figure 4-4 A locked file with the Lock icon in the Status panel 



When you check out a read-only copy of a file from a project, this file will always open in 
read-only mode. The read-only icon is displayed in the status panel, as shown in Figure 4-5. 
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■ Figure 4-5 A read-only file with the Read-Only icon in the Status panel 



Commando dialogs 

The Commando user interface lets you operate any properly configured MPW command 
by means of a special Macintosh dialog, rather than the traditional command line 
interface. Commando dialogs may consist of several dialog boxes containing a variety of 
controls. You can choose options, select filenames, pick directories, and access help 
information for each option. Commando lets you operate MPW commands in a more 
intuitive format. All options are visible, and help text for each option can be instantly 
displayed. 

Because of the complexity of many MPW commands, several specialized controls and 
nested dialog boxes have been implemented for them. The various types of controls and 
dialog boxes are introduced below. Other dialog boxes, specific to a particular 
command, appear together with the command in Part II. 
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Invoking Commando 


There are three ways you can invoke a Commando dialog from the Worksheet: 

■ Option-Enter: Type the command name and then press Option-Enter. This is the 
easiest method for routine interactive use. 

■ Ellipsis: Type the command name followed by an ellipsis character (...) and press 
Enter. You can also use this expression in a script. 

The ellipsis may appear anywhere in a command line (except with quotes or after 3) 
and is considered a word-break character. Although the ellipsis may be situated 
anywhere within the command line, only the first word of the line is actually processed. 
For example, in the command line 

addmenu asm alert... 

only the AddMenu dialog will appear. This results with or without Exit set to 0 or 1. 

The ellipsis invokes the Commando user interface after the Shell has carried out all alias 
and variable substitutions. The entire command line is passed to Commando and the 
output of Commando is then executed by the Shell. 

♦ Important Note: To obtain the ellipsis character, hold down the Option key while 
simultaneously typing the semicolon (;) character. Although three periods closely 
resemble an ellipsis character, Commando won’t be fooled; you must use Option- 
semicolon to get the true ellipsis character that invokes Commando. 

■ Type commando: Type the word commando in front of the command line and press 
Enter. This method of invoking Commando only outputs the command line; the 
command is not executed. You can also use this expression in a script. For example, if 
you don’t want the resulting command line to be immediately executed, you can type 
commando commandname 

The tool’s frontmost Commando dialog box is displayed. Clicking the Do It button 
writes the command line to standard output (that is, the window in which you typed 
the command) instead of executing it immediately. This second method of using 
dialog boxes is useful for building command lines that are to be cut and pasted into 
scripts. In this case, Commando will not find a command if the command has been 
aliased to a different name. 


See “Invoking Commando” in Chapter 13 for more information. 
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Using Commando dialogs 


The function and appearance of Commando dialog boxes may vary widely according to 
the syntax and semantics of the particular command or tool selected. The basic dialog 
box is typical of a simple command such as Date, the first example used in this chapter. 
Type 

Date ... 

Be sure to use Option-semicolon to get the ellipsis. Then press Enter. Figure 4-6 shows the 
resulting Commando dialog box for Date. 

■ Figure 4-6 The Date dialog box 
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Most dialog boxes share the basic structure shown in Figure 4-6. Various controls for 
options and parameters appear in the largest, upper area of the box. Date has three 
parameters: 

Date/Time radio button control 

Amount of Detail radio button control 

Date Input editable field 

The default settings for Date appear preselected as the topmost radio button for each 
parameter. 

Clicking and holding down the mouse button on any control or option displays Help 
information in the standard Help window at the bottom of every Commando dialog box. 
Clicking on the tide of a control also displays the Help information. 

Use the pop-up menu of the Output box to redirect output. See the section “Redirecting 
Output” later in this chapter. 
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The Command Line window displays the command line resulting from the options you 
select from the dialog box. As you select options or change parameters, this Command 
Line box is continuously updated. You can then copy all or any part of the command line 
using Command-C or the Edit menu. 

Clicking the Do It button (the button labelled “Date" in Figure 4-6) passes the completed 
command line back to the Shell for execution. Alternatively, you can press the Enter key. 
If you change your mind and decide to exit from the dialog, you can click the Cancel 
button, which has the same effect as pressing Command-Period. 

You can get these special results by holding down the Option and/or Command keys while 
clicking a Do It button: 

Option key (or pressing Enter) The command line is also written to standard error. 

This means that the command is executed and is 
echoed to the active window. 

Command key The command line is not passed to the Shell; that is, 

nothing is executed. 

Option key and Command key The command line is written to the active window 

without being executed. 


Standard dialog box controls 

This section describes the most frequently encountered Commando dialog box controls. 

Generic text parameters 

Not only do tools have options, they also have parameters. Nonspecific parameters, 
where the parameter can be just about any string, are simply entered in an editable text 
field. For items where text is required, the text is quoted by Commando before being 
passed to the Shell. You can scroll the line right and left (by dragging) if the text in the box 
is longer than the text box. Here’s an example of an editable text field: 


Mark the selection with what name? 
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Repeatable options 

Various text field options, such as the -dfefine] option in Rez and Asm, may be specified 
more than once. The control below shows an option of this type. The number of lines 
displayed is controllable by the tool’s builder. The small window is basically an area where 
text can be entered, very much like the Notepad desk accessory. This window does not 
automatically wrap around lines larger than the window area. Instead, it scrolls left and 
right. You create a new line by pressing the Return key. Scroll the window horizontally by 
dragging. You can scroll the window’s contents vertically either by dragging or by using the 
scroll bar control. 

Preprocessor defines: _ 

Language-english O; 

$ize-height*200 

___|o 


Radio buttons 

Some options ate mutually exclusive and are therefore available as a set of radio buttons. 
The default setting of the button corresponds to the default state of the option. Groups 
of mutually exclusive items are often surrounded with a labeled perimeter: 

-Print Quality— 

OHigh 
®Standard 
O Draft 


Check boxes 

An option, such as the Assembler’s -print option, may have many simultaneous settings. 
Options like this are implemented with check boxes (versus on/off radio buttons). Most 
of the MPW tool’s options are Boolean flags. Check boxes are also used for these types of 
options, and are usually surrounded by a labeled perimeter: 

p Listing Control- 

E3 Show macro expansions 
CS Allow automatic page ejects 
E3 Show warning messages 
^ Show macro call statements 
E3 Show generated object code 

□ Show up to 255 bytes of data 
IS Show macro directive lines 
El Show header lines 

IS Show generated literals 

□ Show assembly status 
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Shadow pop-up menus 

Some options require the name of a window, alias, font, or Shell variable. Commando will 
display a field of this type as a shadowed box: 

Window | HD:OS:U)orte$heet | 

When you click inside the shadowed box, a pop-up menu displays all the choices for that 
particular field (that is, windows, aliases, fonts, or Shell variables). The menu box is 
aligned around the current selection. The current selection is checked in the menu box. As 
long as the mouse button is held down, the menu behaves like a standard pull-down menu. 
If necessary, the pop-up menu will scroll vertically. When the mouse is released within a 
menu item, that item then appears in the shadowed box. 


Ulindoui 

v'HD:OS:lDorksheet 

-1 


HD:MPlll:MyCroft:te$t.c 

HD:MPQI:MyCroft:getopt.c 



Other pop-up variations 

Some options are similar to the pop-up menus above but also allow a little more 
flexibility. The Menu Name box in AddMenu allows you to type in the name of a new menu 
or select an existing menu name from a list of names: 

Menu Name - m 


Click the menu icon at the right of the box to display a pop-up menu containing the 


existing choices: 

Menu Name | 


File 


Edit t 


Find ^ 

Uiindouj 

Mark 

Directory 

Build 


Drag down the pop-up menu until the item you want is highlighted and then release the 
mouse button. The selected item will appear in the text edit box. If you type an item into 
the text-edit box, any identical item in the pop-up menu will be automatically checked. 


CHAPTER 4 Using MPW: The Basics 




















Multiple input files 

When a tool can handle multiple input files of the same type (C, ASM, Rez, and so on), only 
a single button is displayed. 

[ Source Files *] 

Clicking on the button displays a modified standard file dialog box. Commando adds 
some functionality to the standard file package (SFGetFile) to let you select multiple files 
in different directories. Another scrollable list appears under the file list. Use the standard 
file controls to select files and click the Add button to add the selected file to the 
scrollable list under the SFGetFile. After doing so the dialog box does not disappear. 
Instead, the file is added to the lower list. (Alternatively, you can just double-click a 
filename to add it to the lower list.) You can delete a file from the list by selecting it (in 
the lower list) and clicking Remove. You can select several files at once by holding down 
the Command key while you click their filenames. When all desired files have been 
selected, click Done or Cancel to return to Commando’s first dialog box. 

A tool may tell Commando that the tool requires files with a particular extension. A radio 
button lets you display and select any text file (or whatever type of file the tool wants). 
When you select a folder, the Open button reads “Open.” When a file is selected, this 
same button is labeled “Add.” If you select a file that has already been added to the lower 
list, then that file is selected (and scrolled into view if necessary), and the Remove button 
undimmed. 
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^CExamplesj 






Q Count.c 

«Hi 

■ 

c=) HD 



D Memory.c 

D Sample.c 

Q Stubs.c 







c 

i. : je< fc 

D 



c 

Drive 

D 

D testperf.c 








c 

Done 

3 



a 

c 

Cancel 

3 

<§) Files ending in .c O HU text files 



Source: 






:CEKamples:Memot y.c 

a 







C 

Add 

3 



<> 

c 

Remove 

3 


Multiple directories 

Some tools, such as C and Asm, have options that let you specify directories to search 
when looking for various files. Clicking a single button, like this one, will display a 
modified standard file dialog box: 

[Include Directories! 

* 

The selection of multiple directories works in the same way as the selection of multiple 
files. In this example, however, only folders are visible. Because a selected directory has 
the potential for being both opened and added to the lower list, there must be two 
controls for both operations. Clicking the Add button adds the directory selected in the 
upper list to the lower list. The Open button operates in its normal manner: Clicking it 
opens the selected folder. You can delete a directory from the lower list by selecting it (in 
the lower list) and clicking Remove. Finally, clicking Continue or Cancel returns control to 
Commando. 
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(Add Current Directory: ] 



Q Interfaces! 

□ Rlncludes 

□ RStructMacs 

D Clncludes 

D Plnterfaces 

<> 

lj Rlncludes 



<> 


o HD 


[ Eject 1 

[ Dm>e ] 

[ Done ] 

[ Cancel ] 


^Include Search Paths: 



( Open ] 

li « m J 

[ Remoue ] 


Multiple files and/or directories 

For MPW tools or built-in commands that can deal with both multiple files and directories, 
this dialog box, almost the same as the one shown above, lets you select files and 
directories. The model is almost the same as the one above, except that both files and 
folders are visible. Selecting anything in the upper scroll window highlights the lower Add 
button. The controls work as shown in the example above. 

Single input or output file 

You select options or parameters that require a single file (whether for input or output) 
with a control similar to the example below. Clicking in the shadowed rectangle displays a 
pop-up menu with choices depending upon the tool. The first choice can be either 
Default Output or No Output (or, if the file is an input file, Default Input or No Input). 
The Default Output is used for tools that write to a default output file if one is not 
specified. Link and Rez, for example, write to link.out and rez.out, respectively, if no 
explicit output file is specified. If Input File or Output File is selected, SFGetFile (for 
input files), or SFPutFile (for output files) is displayed so that a file can be chosen. If the 
filename selected is too long to fit in the space provided, the middle of the path is 
annotated with An ellipsis (typographical; not a Commando invocation) is added to 
the end of the end if the full filename does not fit within the confines of the box. 

Resource Output FHe|rez.out 
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Here’s an example of an output file pop-up menu: 


v Write output to fiez.ouf 


Select an existing output file... 
Write output to a neiu file... 


Output file where a file or directory may be specified 

The various compilers have options to specify the object filename or the object file 
directory. Commando displays a pop-up menu similar to this one: 


y Itse default naming conuent/on 


| Specify object file name or select directory,.. | 


except that the standard dialog box that appears when you select the Output File or 
Directory item looks like this one: 


[ Select Current Directory: 

) 

|£3 RExamples | 






gzd HD 




1 Oe<< ) 




[ Oriuf* ] 




[Diiec *ory] 

Object File/Directory 


j OK H 

i 

[ 

[ Cancel ] 


The OK button is dimmed when the text-edit box is empty. After entering text into the 
text-edit box, the OK button is highlighted. Clicking the OK button specifies the file as 
the output. Clicking the Directory button specifies a directory as output 
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New directories 


The NewFolder command lets you specify the creation of multiple directories. The 
example below (based upon SFPutFile) is used to create multiple directories. When you 
type a directory name in the middle text-edit area and click the Add button (or press 
Return), a pathname is added to the lower list. The root of the new directory is the same 
as that displayed in the upper scroll list. You can continue to add more directories. Click 
the Done button to close the dialog box and return to the first, or “main” dialog box. 


|QflEKamples| 


D Counts 

O 

oHD 

D Count,!’ 


1 Eject ] 

D Instruction* 

IF 

D MakeFile 


[ Diine ] 

D Memory,a 
<9* Sample 

<> 


New directories: 

[ Done ] 

[ Cancel ] 

i j 




<> 

<> 

I Rdd J 

[ Remoue ] 


Special dialog box controls 

Commando uses standard Macintosh text-edit boxes, radio buttons, and check boxes. In 
addition to these, you’ll encounter some specialized controls because of the variety of 
options and parameters and certain dependencies between them. These various types of 
specialized controls are introduced below. 

Nested dialog boxes 

Some tools, such as Rez and PasMat, have more options and parameters than can fit into 
one dialog box. The additional options are grouped into nested dialog boxes that are 
available from the first dialog box. Figure 4-7 below shows, as an example, the first dialog 
box of Rez. 
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Figure 4-7 Rez: the first dialog box 


r Rez Options- 

Resource Output File- 


Rez.out 


Tgpe 

Creator 


® Rewrite resource file 

□ Make resource file read-only 

-Resource Rlignment- 

<§) Byte O Word O LongUlord 


l O Merge resources into resource file 

□ OK 1« replace protected resoures 


■-Command Line- 


□ Progress information 

□ Redeclared types ok 

□ Modification date 

[ Description Files... ) 

f # Include Paths... ] 

[ Include Paths... ) 

( Preprocessor... ] 

[ Redirection... ] 


Rez 


r Help- 

Rez is a tool used to compile resources. 


[ Cancel ] 



Note the five control buttons at the right side of the “Rez Options” window. When you 
click one of these buttons, a nested dialog box appears with the tide of the selected 
button. For example, selecting the button labeled “Preprocessor..." displays the nested 
dialog box shown in Figure 4-8. 


■ Figure 4-8 Rez: nested preprocessor dialog box 
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As you type in the preprocessor defines and undefines, the command line you began in the 
first dialog box is further updated in the Command Line window of the nested dialog box. 
The lower-right Do It button in a nested dialog box is always labeled “Continue.* Clicking 
Continue closes the nested dialog box, and again displays the first dialog box with the 
command line updated to show the options and parameters selected in the nested dialog 
box. (This is always the case, except for the C compiler dialog, which has a third level of 
dialog boxes.) If you click Cancel, changes from nested dialog boxes are not recorded and 
you return to the first dialog box. From there you can then select another nested dialog 
box. 

Redirecting output 

Every tool that can write information to standard output or to standard error has controls 
to assign destinations for this output. Consider the Error Output window in the 
Redirection nested dialog box of Rez, shown in Figure 4-9. 

■ Figure 4-9 Rez: nested Redirection dialog box 


i-Bez Options ■ — 7 1 
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Clicking inside the Error window (and holding the mouse button down) displays this pop¬ 
up menu: 

Error _ 

V No Output Be direct Jon 
Neui File... 

Existing File... 

Window... 

Current Selection in Window... 

Current Selection In Target Window 
Standard Output 
Standard Diagnostic 


Null Dei'ice 


| Console ^ | 

Here Null Device has been selected. When the mouse is released, the filename devmull 
appears in the Error window. Whenever you select an output redirection, the two invisible 
radio buttons directly above the error pop-up are activated. 

Selecting “Existing File...” in the pop-up menu displays the standard file dialog box. 
Selecting “New File” brings up the standard output file dialog box and lets you create a 
new file. Selecting “Window...” brings up a list of the active windows to choose from. 
Because a window is a file, you could also choose a window with the Existing File 
command. 

Selecting Current Selection in Window also brings up a list of windows to choose from. 
When you select Current Selection in Target Window, output is redirected to §. When you 
choose a window, output is redirected to window When you choose any file other than 
a new file, the Overwrite and Append radio buttons are activated. These buttons 
correspond to the functions of the >> and », >> redirection operators, respectively. 
Selecting No Output Redirection clears the pop-up menu so that no redirection occurs. 

After you release the mouse over Null Device, the command window looks like this: 

Error ®> Q>> 

|Deu:Null | 

The Diagnostic Output windows and Standard Input windows (in the case of tools that 
read standard input) work in a similar fashion. 
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Options dependent on other options 

Some options may be dependent on other options. For example, the -hf (header font) and 
-hs (header size) options of the print tool don’t mean anything unless the -h (header) 
option is specified. Commando implements this model by disabling all controls 
dependent upon some other control. When you check (or otherwise activate) the main 
control, the dependent controls are enabled. Another example is the AddMenu command. 
The syntax of this command is 

AddMenu [menuName [itemName [command...] ] ] 

An itemName cannot be entered until a menuName is entered. Likewise, a command 
cannot be entered until an itemName is entered. 


Menu Name 
Item Name 



Command* 


Here is the same set of options after “Find” has been typed in the first text-edit entry 
field. Notice that as soon as something is entered in the field, the Item Name entry is 
enabled, but the Commands field remains dimmed. 


Menu Name 
Item Name 


Find gj 

: • b 


Command* 


When an item is selected from the Item Name pop-up menu or simply typed into the Item 
text-edit box, the Commands field is enabled. If Find is a valid menu name, then Find’s 
menu items will appear in the Item Name pop-up menu. 


|Find 

m 

| Replacej 

_ID 


Commands 

- -P 

_ Q 


There may be several text-edit boxes that are disabled (dimmed) until you have entered 
something in the adjacent enabled text-edit box. 
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Three-state controls 

Some options, like the -a option of Setfile, need the support of a three-state control. For 
example, Setfile can set, clear, or do nothing to the bundle bit. Clicking this control cycles 
through its three states. The color of the diamond determines its state: 

Gray Don’t touch the flag 

White Clear the flag 

Black Set the flag 




i— Attributes- 

O Locked 
O Inuisible 

♦ Bundle 

♦ System 
^ Protected 

♦ Open 

^ Changed 

♦ Inited 

<0> on Desktop 
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Chapter 5 Using the Command Language 


This chapter describes the complete syntax of the mpw 3.0 command 
language and explains its use. Each command is defined in detail in Part II. 
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“AddMenuAsGroup” 169 
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Overview 


The command language provides the following features: 

■ Built-in and user-definable variables of the form [variableNamd 

■ Command aliases, used to create alternative names for commands 

■ Command substitution, by which commands enclosed in back-quotation marks 
('...') are replaced by their output 

■ A quoting mechanism for disabling special characters or inserting invisible characters 
in text: d literalizes a single character; '...' and "..." quote strings 

■ An extensive set of structured commands for controlling the order of command 
execution, including Begin...End, If...Else...End, and For...In...End 

■ Filename generation with “wildcard” operators such as « and ? 

■ Redirection of input and output with the <, >, », >, >>, X, and XX operators 

When you enter command text, the Shell first interprets and processes all special symbols 
before actually running the command. The order of interpretation is explained later in this 
chapter under “How Commands Are Interpreted.” For the most part, the order of 
presentation in this chapter follows the order of interpretation by the Shell. 

In order to begin using MPW, you should read the following sections of this chapter at a 
minimum: 

■ The opening sections of the chapter, which describe the basic form of all commands: 
Types of Commands,” “Entering and Executing Commands,” and “Structure of a 
Command” 

■ “Command Scripts” and “Special Scripts” 

■ “Variables” 

■ “Quoting Special Characters” 

The operators and syntax of the command language are summarized in Appendix D. 
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Types of commands 


In all, four kinds of commands are provided: 

■ Built-in commands, such as Files or Duplicate, are part of the MPW Shell. 

■ Command scripts, such as Startup, are text files that contain commands. You can 
combine any series of MPW commands in a text file, and execute the file by entering 
its filename, just like any other command. You can also pass parameters to a script 
and use them in commands within the file. 

■ Tools, such as Link or Asm, are executable programs (that is, separate files on the 
disk) that are fully integrated with the Shell environment. 

■ Applications, such as ResEdit or MacPaint®, are stand-alone programs that can be 
launched from the Shell but can also run outside the Shell environment 

To execute a tool, application, or script, you need to have the proper program file 

on your disk. 

♦ Note: A built-in command overrides a script or executable program with the same 
name. You should therefore use either full pathnames or quotation marks to specify a 
script or program with the same name as a built-in command. (Quotation marks work 
for this purpose because the names of built-in commands must appear unquoted—see 
“Quoting Special Characters” later in this chapter.) 

♦ Note. The Shell will not execute a tool whose modification date is 12:00 A.M. 1/1/04. 


Entering and executing commands 


Press the Enter key to execute selected command text. If no text is selected, pressing 
Enter executes the entire line that contains the insertion point. Alternatively, you can use 
the mouse to click the Status Panel in the Worksheet’s lower-left comer, or press 
Command-Return; both methods have the same result as pressing the Enter key. 

A Important If no text is selected, pressing Enter always passes the entire line to 
the Shell (or to whatever other program happens to be reading from 
the console). This rule also applies to your own integrated programs 
that run within the Shell, a 
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A Important If you enter a line that ends with the Shell escape character, d, the 
command interpreter will pause, waiting for the rest of the line, a 


All commands return a status code. 0 indicates successful completion; nonzero values 
usually indicate an error. This code is returned in the {Status} variable, described later in 
this chapter. 


Negative status codes 

The command interpreter will return negative status codes when it encounters an error. 

These codes are: 

-1 Command not found, script is a directory, script is not 
executable, or script has a bad date. 

-2 Filename expansion failed, or there was an error in the expression 
syntax. 

-3 Bad syntax. Quotation characters and braces were not balanced, 
or were missing end or “)” command. Error in control constructs. 

-4 Missing filename following I/O redirection or the file could not 
be opened. 

-5 Invalid expression (If, Break If, Continue If, and other such 
constructs). 

-6 Tool could not be started. 

-7 Runtime error during tool execution, most likely an out-of- 
memory error. 

-8 User aborted the tool from the debugger. 

-9 User aborted the tool with Command-period. 

These values can be used to distinguish between errors returned by the commands 

themselves and errors returned by the Shell. 

A Important All negative numbers are reserved for the Shell. Use only positive 
numbers for errors in tools or scripts, a 
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Structure of a command 

A command is written as a list of words separated by blanks. (Blanks may be either space 
or tab characters.) The first word is the name of the command, and each word that follows 
is passed as a parameter to the command. The general form of a simple command is 

commandName [parameters...] commandTerminator 
Each of these elements is described below. 


Command name 

The command name is either the name of a built-in command or the filename of the 
program or script to execute. Command names are not case sensitive. Alternative names 
can be defined for a command—see “Command Aliases” in this chapter for information. 

The command name is passed to tools and scripts as parameter 0, and can be referenced 
by scripts in the variable {0}, explained later in this chapter under “Variables.” 


Parameters 

Each of the subsequent words in a command is a parameter to the command or to the 
command interpreter. Note that certain parameters, such as I/O redirection, are 
interpreted by die Shell, and never seen by the command itself. Variables are also 
interpreted before being passed to the program. 

By convention, there are two distinct types of parameters to commands: options and 
files. See the “Command Prototype” section at the beginning of Part n for more details 
on these conventions. 

You can reference parameters within scripts by using the variables { 1 }, {2},... {«}. (See 
Table 5-5.) 
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Command terminators 


Each command is normally terminated by a return character. Commands can also be 
terminated by the pipe symbol (I), the conditional execution operators (&& and II), or 
the simple command terminator (;). Each of these symbols may be followed by a return. 
Table 5*1 describes the command terminators in order of decreasing precedence. 

Except as modified by structured commands, commands are read sequentially and 
executed as they are read. 


■ Table 5*1 Command terminators 


Command Description 


cmdl I cmd2 

cmdl && cmd2 

cmdl 11 cmd2 
cmdl ; cmd2 


Saves the standard output of cmdl in a temporary file and uses it as 
the standard input of cmd2. (Standard I/O is explained later in this 
chapter.) 

Note: In MPW, unlike UNIX® systems, the commands are executed 
sequentially. 

Executes cmd2 only if cmdl succeeds (that is, returns a status value 
of zero). 

Executes cmd2 only if cmdl fails (returns a nonzero status value). 

Executes cmdl followed by cmd2; this terminator allows more than 
one command to appear on a single line. 


These command terminators may be applied to both simple and structured commands. 
Grouping is from left to right You can use parentheses to group commands for 
conditional execution and pipe specifications. Here are some examples: 

Files I Count -1 

This command pipes the output of the Files command (a list of files and directories) to 
the Count command, which counts the lines in the list 

Asm Sample.a && Link Sample.a.o -o Sample.code I I 
(Echo Failed; Beep) 

This example begins by assembling Sampler. If that operation succeeds, it links the 
object file; but if the assemble-and-link operation fails, it echoes the message “Failed,” 
and beeps. 
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Command continuation 


You can continue a command onto the next line by typing 9 (Option-D) followed by a 
return. Both characters are discarded when the line is interpreted. The return must come 
immediately liter the 9, with no blanks or comments between them. (For more 
information about the 9 escape character, see “Quoting Special Characters” in this 
chapter.) 

Echo This is all d 
one command 

This is all one command 
Notice that the output appears on one line. 


Comments 

The number sign (#) indicates a comment. Everything from the # to the end of the line is 
ignored. (Comments always end at the next return, even if the return is preceded by a 9.) 

Echo This is echoed. # This is not. 

Echo parameters # comment 9 

more parameters # another comment 


Simple versus structured commands 

All of the commands introduced so far have been simple co mmands . Simple commands 
consist of a single keyword, followed by zero or more parameters. Simple commands are 
distinguished from structured commands—commands such as For and If, for example, 
that let you control the order in which other commands are executed. For example, 

For file In =.c; Count {file}; End 

All structured commands are built-in, and usually have more than one keyword. The entire 
structured command is read before its execution begins. 

Also see “Structured Commands” in this chapter. 
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Running an application outside the Shell enTironment 

You can run an application outside the MPW Shell environment by executing the program 
name just like any other command. For example, 

ResEdit 

The application is loaded and launched as if it had been started from the Finder. Any Files 
specified as parameters are passed to the program via the application parameter handle, 
in Finder fashion. (See “Finder Information” in the chapter “Segment leader” of Inside 
Macintosh .) The following option is available on the command line: 

-p file... Tell the program to print the specified files. 

For example, 

MacPaint -p "HD:Screen 1" "HD:Screen 2" 

This command tells the Shell to run MacPaint (assuming MacPaint is in a directory listed in 
the Shell variable {Commands}), and to print the files Screen 1 and Screen 2. 

The Shell environment is saved when the application is launched and restored when the 
application terminates. (These actions are performed by the Suspend and Resume 
command files, described below.) 

♦ Note: When r unning MPW under MultiFinder, the application is launched into a 
separate MultiFinder partition and the state is not saved. 

▲ Warning Running an application from a script normally terminates the script. 

Under MultiFinder, the application starts and the script continues to 
execute, a 
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Scripts 


You can create your own commands by writing text files of previously defined commands, 
called scripts (command files). You can execute such a file just like any other command 
within the Shell environment—the name of the file you created is the name of the new 
command. For example, 

Date 

Echo Volumes. 

Volumes 

Echo Current Directory. 

Directory 

Echo Files. 

Files 

If this text is on the screen, you can execute it by selecting it and pressing Enter. You can 
also save this text as a script so that it’s always available. To save it under the name “Info," 
for example, first select the command text, making sure that the window with the 
selected text is the target (second from the front) window. Then type the following 
command in another window: 

Duplicate -d § info 

You can now execute this series of commands by entering the command name Info. 

(Recall that the § character indicates the selection in the target window.) 

You can pass parameters to a script just as you would to a predefined command by using 
the normal Shell syntax: 

filename [parameters...] 

Parameters can be referred to within the scripts by using the built-in variables {l}, 

{2},...{»}, explained below under “Parameters to Scripts.” 


♦ Note: As a matter of convenience, scripts (as well as applications and tools) are usually 
kept in directories that the Shell automatically searches when a leafname is given for a 
command name. This convention allows you to invoke the command by using its 
leafname instead of its full pathname. The Shell variable {Commands} contains a 
comma-separated list of directories to be searched. You can easily modify it to 
include additional directories. 
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Special scripts 


The scripts described in this section are provided with MPW. You can modify the 
commands in each of these files to suit your needs. 


A im portant Each of these scripts must be in the same directory as the MPW Shell, 
or in the System Folder, a 


The Startup and UserStartup files 

When you start up the Shell, commands are initially read from a file named Startup. The 
Shell executes the commands in Startup as if you had entered them interactively. The 
Startup file provided with MPW contains several default variable and alias definitions. 

You can modify the commands in Startup to suit your own needs; for instance, you can 
change the default pathnames to suit a special directory configuration. 

Startup executes another script called UserStartup. It’s recommended that you use this file 
for your own changes and additions to the startup sequence. You can redefine the 
variables defined in Startup, set and export any number of additional command-language 
variables, and define aliases and create menu items. Aliases and variables are fully 
described in the sections that follow. 


Suspend, Resume, and Quit 

When you run an application from the Shell, commands are read from the file Suspend. 
When you quit the application and return to the Shell, commands are read from the file 
Resume. The Suspend and Resume files save state information about variable definitions, 
exports, aliases, and windows before running an application; they then restore the state 
after returning to the Shell. 

♦ Note: Suspend and Resume are not used if the MPW Shell is running under MultiFinder. 

When you quit from the Shell, commands are read from the file Quit. The Shell executes 
these commands before closing any windows. 
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♦ Note: If you cancel from the Quit command, the Quit file will already have been 
executed. 

Like Startup and UserStartup, these scripts run as if you had entered the commands 
interactively. You can modify them to suit any special requirements you may have. 


Command aliases 

An alias is an alternative name for a command (and possibly some parameters). The Alias 
command is used to define aliases and to display the list of aliases. If an alias has been 
defined, it will be recognized by the command interpreter and the corresponding 
definition will be substituted. 

♦ Note: Variable substitution and alias substitution occur on the alias definition itself 
after it has been substituted. 


The following commands are used to define and undefine aliases: 


Alias name word... 
Alias name 
Alias 

Unalias name 
Unalias 


Name becomes an alias for the list of words. 
Displays any alias definition associated with name. 
Displays all alias definitions. 

Removes any alias definition associated with name. 
Removes all alias definitions. 


Aliases are local to the script in which they are defined (and are globally available if they 
are defined in the Startup and UserStartup files or entered interactively). Aliases are 
automatically inherited from enclosing scripts, and they may be redefined locally. 
However, aliases redefined locally will revert to their previous value when the script 
terminates. 


See the Alias and Unalias commands in Part II for a complete specification of aliases and 
several examples. 


132 MPW 3.0 Reference 








Executable error messages 

The following alias is defined in the Startup file: 

Alias File Target 

That is, the word “File” is defined as an alias for the Target command, which opens a file as 
the target window. (See Chapter 6, “Editing Commands.”) This alias is useful when a 
compiler returns an error message such as 

### Not a parameter name: counts 
File "Count.c" ; line 73 

By placing the insertion point anywhere on the error message line or by selecting the entire 
line and pressing the Enter key, you’ll automatically open the specified file as the target 
window, find and select the offending line, and bring the window to the top. The 
command that the Shell actually executes is 
Target "Count.c" ; Line 73 

line is a script that automatically finds and selects a line by number and then brings the 
target window to the top. 


Variables 

The Shell provides several predefined variables and allows you to declare any number of 
additional variables. Variables are used for 

■ shorthand notation 

■ status information 

■ local variables in scripts 

■ parameters to scripts and tools 

■ certain defaults for the MPW Shell 

You an define or redefine variables with the Set command and remove variable 
definitions with the Unset command. For example, the command 

Set PFiles HD:MPW:PFiles: 

defines a variable {PFiles} with the value “HD:MPW:PFiles:”. 
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Variables have strings as their values. You can reference them by using the notation 
{name}, where name is the name of the variable. When a command containing a variable 
{name} is executed, {name} is replaced with the current value of the variable. In this 
example, 

Files {PFilesJSrc.p 

{PFiles} is replaced with its definition before the command is executed. 

A variable may comprise one or more words, or part of a word. If a variable is undefined, 
{name} is removed (that is, replaced with a string of length zero, called a null string). 

Variable names are case insensitive, and must not include the right brace character (}), for 
obvious reasons. It’s wise to avoid using any special characters in variable names because 
future extensions to the command language may assign special meanings to some of these 
characters. 

♦ Note: For variables such as {Exit} and {CaseSensitive} that can be either “true” or 
“false," the variable is considered true if it is set to anything other than zero or the null 
string (a string of length zero). The variable is considered false if it is set to zero, null, 
or undefined. The best way to set one of these variables is like this: 

Set Exit 1 # turn {exit} on 

Set Exit 0 # turn {exit} off 

(These values also apply to expressions that return a Boolean value, defined later in 
this chapter under “Structured Commands.”) 


Predefined variables 

Table 5-2 lists the variables defined by the MPW Shell. These variables provide the 
status value returned by the last command as well as the pathnames of several files 
and directories. 

A Important Since the variables listed in Table 5-2 are predefined or defined 

dynamically by the Shell, you should not modify the values of these 
variables, a 
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■ Table 5-2 

Variables defined by the Shell 

Variable 

Description 

{Active} 

Full pathname of the current active window. 

{Aliases} 

A list of all defined aliases, with each name separated by a comma. 

The list contains only the names, not the definitions. Commando 
uses this variable with the built-in commands Alias and Unalias. 

Commando needs this variable to know the names of existing 
variables. {Aliases} must be exported. 

{Boot} 

Volume name of the boot disk. 

{Command} 

Full pathname of the last command executed. (For built-in 
commands, this is the name of the command.) 

{ShellDirectory} 

Full pathname of the directory that contains the MPW Shell. 

{Status} 

Result of the last command executed. (A value of 0 means successful 
completion. Any other value is an error code: Typically, 1 means an 
error in parameters, and 2 means that the command failed.) 

{SystemFolder} 

Full pathname of the directory that contains the System and Finder 
files. 

{Target} 

Full pathname of the target window. The target window is the second 
window from the top; by default, this is the window where editing 
commands (such as cut, copy, and paste) take effect 

{Windows} 

Contains a list of the current windows, with each name separated by 
a comma. Commando uses this list to allow redirection of output or 
input to or from existing windows. Commando needs this variable to 
know the names of the current windows. {Windows} must be 
exported. 

{Worksheet} 

Full pathname of the Worksheet window. 


Variables defined in the Startup file 


Table 5-3 lists the variables defined in the Startup file (described in the “Special Scripts” 
section earlier in this chapter). These variables define pathnames and default settings to 
the Shell and are referenced by the Shell and by some of the MPW tools. You can change 
any of these definitions to suit your preferences. 

Hierarchical file system (HFS) pathname conventions are described in Chapter 4 . 
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■ Table 5-3 Variables defined in the Startup file 


Variable Description 


Variables referenced by the command interpreter 

{Commando} This variable tells the Shell which command to execute when the 
ellipsis character (Option-semicolon) is present anywhere in a 
command line. The Startup file sets this variable to “Commando.” The 
{Commando} variable allows the development of similar tools whose 
output is to be executed by the Shell. If the variable is not set, then 
the ellipsis character is removed from the command line and normal 
execution proceeds. {Commando} must be exported if scripts are to 
use Commando. 

{MPW} The volume or folder containing the Macintosh Programmer’s 

Workshop. Initially set to the directory containing the MPW Shell. If 
you put the MPW Shell on your desktop, modify the value of {MPW} 
in the Startup file. 

{Commands} A list of the directories that the Shell searches when looking for a 
command to execute. Directories in the list are separated by 
commas. A single colon indicates the default directory. {Commands} 
is initially set to 

{MPW}Tools:,{MPW}Scripts: 

—that is, the current directory; then HD:MPW:Tools, then 
HD:MPW:Scripts, and then HD:MPW:Applications (assuming that 
{MPW} is set to HD:MPW:). 

{Echo} When {Echo} is set to a nonzero value, commands are written to 

diagnostic output after aliasing, variable substitution, command 
substitution, and filename generation, and just prior to execution. 
This capability is useful for watching the progress of a script and for 
debugging scripts. As the first line of your file, include the line 

Set Echo 1 
{Echo} is initially set to 0. 

{Exit} When {Exit} is set to a nonzero value, scripts terminate whenever a 

command returns a nonzero status. This nonzero status is returned as 
the status value of the script. (See the {Status} variable in Table 5-2.) 
{Exit} is initially set to 1. 

{Test} When {Test} is set to a nonzero value, the command interpreter 

executes built-in commands and scripts, but not tools or 
applications. {Test} is useful for checking the control flow in 
command files. (It’s most useful if {Echo} is also nonzero.) {Test} is 
initially set to 0. 

(Continued) 
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■ Table 5-3 (Continued) Variables defined in the Startup file 

Variable_Description 

Variables referenced by the editor 


{Autoindent} 

{CaseSensitive} 

{Font} 

{FontSize} 

{PrintOptions} 


Specifies the setting for automatic indenting. The default setting for 
a new window is 1. If {Autoindent} is set to any value greater than 0, 
automatic indenting occurs. 

Any nonzero value specifies case-sensitive pattern matching. 
{CaseSensitive} is initially set to 0 (that is, false). You can also set 
{CaseSensitive} from the Find and Replace dialog boxes, by clicking 
the Case Sensitive button. (See “Find Menu” in Chapter 3.) 

Specifies the font for a new window. Its predefined value is 
“Monaco.” 

Specifies the font size for a new window. It is preset to 9. 

Options used by the Print Window and Print Selection menu items. 
They are initially set to -h. (The -h option prints pages with headers. 
For more information on possible print options, see the Print 
command in Part II.) 


{SearchBackward} If set to any nonzero value, searching will proceed backward. This 
variable can be used to set up the default environment so that you 
can access the backward search option. The default value is 0. You 
can also set {SearchBackward} from the Find and Replace dialog 
boxes by clicking the Search Backward button. (See “Find Menu” in 
Chapter 3.) 


{SearchType} 


{SearchWrap} 


{Tab} 


Use this variable to set up the default environment so you can access 
selective search options. If {SearchType} is set to 0, the search will 
find the literal character string specified. If it is set to 1, only words 
will be searched. If set to 2, regular expressions will be searched. The 
default value is 0. You can also set {SearchType} from the Find and 
Replace dialog boxes by clicking one of the Literal, Word, or 
Selection Expression buttons. (See “Find Menu” in Chapter 3.) 

Use this variable to set up the default environment for wrap-around 
searching. If set to any nonzero value, searching will wrap around. The 
default value is 0. You can also set {SearchWrap} from the Find and 
Replace dialog boxes, by clicking the Wrap Around button. (See 
“Find Menu” in Chapter 3.) 

Default tab setting for new windows (initially 4). 


(Continued) 
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■ Table 5-3 (Continued) Variables defined in the Startup file 


Variable 

Description 

— 

Variables referenced by the editor (Continued) 


{User} 

The name of the current user of MPW, predefined to be the same as 
the user name specified in the Chooser. 


{WordSet} 

The set of characters that constitute a word to the editor (for use 
with Find and Replace menu commands, and for word selection by 
double-clicking). By default, {WordSet} is set to the characters a-z, 

A-Z, 0-9, and _ (underscore). If a character is not in the list, the 
editing commands regard it, like a blank, as a break between words. 


Pathnames for libraries and Include files 


{AIncludes} 

The directories to search for assembly-language Include files, 
referenced by the Assembler. Initially set to 

" {MPW} Interfaces:AIncludes: ". 


{CIncludes} 

The directories to search for C Include files, referenced by the C 
compiler. Initially set to 

" {MPW}Interfaces:CIncludes: 


{CLibraries} 

The directory that contains C library files. Initially set to 
n {MPW}Libraries:CLibraries: ". 


{Libraries} 

The directory that contains shared library files. Initially set to 
" {MPW} Libraries: Libraries:". 


{PInterfaces} 

The directories to search for Pascal interface files, referenced by the 

Pascal compiler. Initially set to. 

"{MPW}Interfaces:PInterfaces:" 


{PLibraries} 

The directory that contains Pascal library files. Initially set to 
"{MPW}Interfaces:PLibraries:". 


{RIncludes} 

The directory that contains Resource compiler (Rez) Include files. 

Initially set to 

"{MPW}Interfaces:RIncludes:". 
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UserVariables 


UserVariables is a script that lets you use Commando to create Set commands for user 
variables that you may wish to include in your startup script. Paste the command line 
created by Commando into your User Startup file and format it as you like. Note that the 
commands are separated by semicolons. Don’t forget to remove the UserVariables 
command from the beginning of the command line. 


The variables in the UserVariables script are divided into six groups: 


Control Variables 
Search Variables 

Print Options 
Window Stacking 
Window Tiling 
Window Variables 


{Echo}, {Exit}, {IgnoreCmdPeriod}, and {Test} 

{SearchType}, {CaseSensitive}, {SearchBackward}, 
{SearchWrap}, and {WordSet} 

{PrintOptions} 

{StackOptions} 

{TileOptions} 

{NewWindowRect}, {ZoomWindowRect}, {Autoindent}, 
{Font}, {FontSize}, and {Tab} 


These variables are described in Table 5-4 that follows and in Table 5-3 in the previous 
section. 
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■ Table 5-4 User variables not defined in Startup file 


Variable Description 


{DirectoryPath} Use this variable to change directories easily. {DirectoryPath} is 
searched by the Directory command when you attempt to set a 
directory by using only its leafname. (See Directory in Part II.) 

{IgnoreCmdPeriod} This variable tells scripts to ignore Command-Period. This is useful 
for critical sections of a script If this variable is set to a nonzero 
number, Command-Period is ignored. Tools that run in the scope that 
has {IgnoreCmdPeriod} defined will also ignore Command-Period. 

This overrides any signal handler defined in the tool itself. 
{IgnoreCmdPeriod} is undefined at startup. 

A Important If {IgnoreCmdPeriod} is set, the only way to 
prematurely stop execution is to reboot a 

{NewWindowRect} Specifies the window size when a new window is created. The value 
of this variable is the four coordinates of a rectangle, listed in this 
order: top, left, bottom, right. The defined rectangle must be visible 
on the Macintosh screen. If the rectangle specified is not totally 
visible it is clipped to the edges of the screen. The coordiates (0,0) 
are at the left side of the screen at the bottom of the menu bar. For 
example, to create all new windows in the top left comer of the screen 
400 pixels wide and 200 pixels high, use the following command: 

Set NewWindowRect 0,0,400,200 

{StackOptions} Options used by the Stack Windows menu command. Use this 

variable to specify your own preferences. (See “Window Menu” in 
Chapter 3.) 

{TileOptions} Options used by the Tile Windows menu command. Use this variable 
to specify your preferences. (See “Window Menu” in Chapter 3.) 

{ZoomWindowRect} 

Specifies the size of a window when it is zoomed to full screen size. 
The value of this variable is the four coordinates of a rectangle, listed 
in this order: top, left, bottom, right. The defined rectangle must be 
visible on the Macintosh screen. If the rectangle specified is not 
totally visible, it is clipped to the edges of the screen. The 
coordinates (0,0) are at the left side of the screen at the bottom of 
the menu bar. 
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Parameters to scripts 

When a script is executed, the values of certain Shell variables are set automatically. These 
variables are explained in Table 5-5. 

■ Table 5-5 

Parameters to scripts 

Variable 

Description 

{0} 

Name of the currently executing script. 

{1}, {2},...{*} 

First, second, and nth parameter passed to the current script 
(These values are null for commands entered interactively.) 

{#} 

Number of parameters (excluding the command name). 

{Parameters} 

Equivalent to {1} {2} ... { n> . 

{"Parameters"} 

Equivalent to " { l }" " { 2 }" { n) -. This form should be 

used if the parameters could contain blanks or other special 
characters. 


The {Parameters} variable is especially useful when the number of parameters is unknown. 
The quoted forms, such as "{1}" or {"Parameters"}, are usually preferable to the unquoted 
forms because, after variable substitution, U), {2}, and so on could contain blanks or other 
special characters. For example, consider the Line script (which is useful with error 
messages, as explained earlier in this chapter under “Executable Error Messages”): 

Find ’'{I}” "{Target}” # Find line n in the target window. 

Open "{Target}" # Make the target window the active 3 

# (top) window. 

This script takes one parameter, a line number. Parameter {1} is quoted to handle the case 
where Line is called without any parameters. In this case the value of {1} is the null string, 
and without the quotes the {1} would completely disappear, leaving the name of the target 
window as the only parameter to Find. The quotation marks ensure that at least a null 
string is sent to Find as its first parameter—this is essential, because the window name 
must be the second parameter. Also notice that the {Target} variable is quoted, because it 
is a filename that might contain blanks or other special characters. (For more information 
on quoting rules, see “Quoting Special Characters” later in this chapter.) 
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Defining and redefining variables 


The following commands are used to define and modify variables: 


Set name value 
Set name 
Set 

Unset name 


Assigns the string value to variable name. 

Writes the value of variable name to standard output. 

Writes a list of all variables and their values to standard 
output. 

Removes the definition of variable name. 


Unset Removes the definition of all variables in the current scope. 

(For an explanation of the scope of a variable, see the next 
section.) 


▲ Warning Removing all variables in the outermost scope can have serious 

consequences. For example, the Shell uses the variable {Commands} to 
locate MPW tools and other commands. The assembler and compilers 
use other variables to help locate Include files. Some variables, such as 
{Boot}, cannot be reinitialized without restarting MPW. a 

Defining a variable and making it available for use by scripts and programs involves two 

separate steps: 

1. You can define a variable with the Set command. Note that variables are local to the 
script in which they are defined—a variable definition ceases to exist when its 
command file terminates. 

2. You can pass a variable to scripts and tools with the Export command. After you 
export a variable, nested scripts can reference that variable and may override its value 
locally—but any redefinition is strictly local and terminates when the script 
terminates. It’s impossible to affect the value of a variable in an enclosing script. (See 
Figure 5-1.) 


Exporting variables 


The Export command makes variables available to scripts and tools: 


Export name... 
Export 

Unexport name... 
Unexport 


Exports the named variables. 

Writes the list of exported variables to standard output. 
Removes specified variables from the list of exported variables. 
Writes the list of unexported variables to standard output. 
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You can define a variable globally by setting its value in the Startup file and exporting it. 
Figure 5-1 illustrates how Export works. 

■ Figure 5-1 Trafficking in variables 


### UserStartup File ### 
Set var X 
Export var 


# (var) = ’X* 
ACommandFile 


### ACommandFile ### 
Set Var Y 
Export var 
Set local Z 
AnotherCommandFile 


### AnotherCommandFile ### 

# (local) is undefined 

# (var) = T 
Set var Z 

# (var) = T 


# (var) = *Y’ 

# (local) = T 


# (var) = ’X’ 


♦ Note: You can use the Execute command to execute a script without creating a new 
scope for variables, exports, and aliases. The Shell “executes” the Startup, Suspend, 
Resume, and Quit scripts, and Startup uses Execute to run the UserStartup script. For 
more details about Execute, see Part II. 
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Command substitution 


Command substitution causes a command to be replaced by its output. You can specify 
command substitution by enclosing one or more commands in backquotes (). The 
backquote key is located at the upper-left comer of the original Macintosh keyboard; it 
is located near the space bar of the newer keyboards. When the command is executed, the 
standard output of the enclosed commands replaces the Command substitution can 
form part of a word, a complete word, or several words. Command substitution is not 
done within “hard” quotation marks (that is, the standard single quotation marks 

♦ Note: If the standard output of the enclosed commands contains return characters, the 
returns are replaced by blanks. If the output ends with a return, this return is 
discarded. 


For example, the command 

Echo The date is 'Date' 

echoes the parameters, replacing the Date command with its output, as follows: 

The date is Wednesday, October 22, 1987 10:40:00 PM 

The following example duplicates the files whose names are output by the Files command: 

Duplicate 'Files -t MPST MyDisk:' "{MPWJTools" 

The command line 

'Files -t MPST MyDisk:' 

is replaced with a string of filenames of type mpst (that is, MPW tools) before the 
Duplicate command is executed; these files are then copied to the folder {MPWjTools. 
This command is useful because the Files command allows you to specify files with a 
certain type or creator, something you can’t do with wildcard operators. 
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Filename generation 

After variables have been substituted, an unquoted word that contains any of the 
characters 

? = [ * + « 

is considered a filename pattern. The word is replaced with an alphabetically sorted list of 
filenames that match the pattern. An error is returned if no filename is found that matches 
the pattern. 

You can specify a group of file- (or window-) names with the “wildcard” notation given in 
Table 5-6. 


■ Table 5-6 

Filename generation operators 

Variable 

Description 

? 

Matches any single character (except a colon). 


Matches any string of zero or more characters (except a colon). 

[ characterList] 

Matches any character in the list 

b characterList] 

Matches any character not in the list 

* 

0 or more repetitions of the preceding character or character list (?* is 
the same as =). 

+ 

1 or more repetitions of the preceding character or character list. 

«number of repetitions» 

Specifies number of repetitions of the preceding character or 
character list. 


The pathname separator (:) must appear explicitly in the pattern because the : character 
will never be substituted for ?, =, or [...]. 

♦ Note: Pattern matching is not case sensitive. 
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These special characters are the same regular expression operators used in editing 
commands. For a complete discussion of regular expressions, see Chapter 6. 

Naturally, you need to be careful with these wildcard operators. The Parameters and Echo 
commands are very useful for double-checking which filenames a command will generate. 
For example, before giving the command 

Delete ~.c.o 

you might want to am the command 
Parameters =.c.o 

This command lists your “.c.o” files to standard output so that you can make sure you 
really want to delete them all. 

♦ Note: Wildcard characters only generate names that match existing filenames; they do 
not create new files. For example, the following attempt to rename files will not work: 

Rename =.obj =.o 

An example of how to perform a wildcard rename can be found under the description 
of the Rename command in Part E 


Quoting special characters 

There are numerous characters that have special meanings to the MPW Shell. Normally, the 
Shell performs the action indicated by the special character—but you can disable a 
character’s special meaning (that is, include it as a literal character) by quoting it You 
commonly need quotes when specifying filenames that contain blanks or other special 
characters or when searching for the literal occurrence of a special character. See also 
“Pattern Matching” in Chapter 6. 

Table 5-7 lists all of the special symbols recognized by the Shell. 
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■ Table 5-7 Special characters and words 


Character Meaning 


Where described 


Space Separates words 

Tab Separates words 

Return Separates commands 

; Separates commands 

I Separates commands, piping output to input 

&& Separates commands, executing the second 

if the first succeeds 

I | Separates commands, executing the second 

if the first fails 

(...) Command grouping; grouping in filename 
generation 
Invokes Commando 


“Structure of a Command” 

“Structure of a Command” 
Table 5-1 


‘Invoking Commando” 


# 

d 

t I 

tv tv 

/."/ 

\...\ 

{...} 


[...] 

* 

+ 

« » 


♦ Note: This ellipsis character is an Option-semicolon key command, not 
three periods. 

Comments “Structure of a Command” 


Escape character: quotes the In this section (Table 5-8) 

subsequent character 

Quotes all special characters 

Quotes all special characters, except d, {, and' 

Quotes all special characters, except d, {, and' 

Quotes all special characters, except d, {, and' 

Variable substitution “Variables” 

Command substitution “Command Substitution” 


Matches a single character in filename “Filename Generation” 

generation. In this chapter 

Matches any string in filename generation “Pattern Matching” in 

Chapter 6 

Character list in filename generation 

Zero or more repetitions in 

filename generation 

One or more repetitions in filename 

generation 

Specified number of repetitions in filename 
generation 


(Continued) 
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Table 5-7 (Continued) Special characters and words 


■ 


Character Meaning 


Where described 


< Input file specification “Redirecting Input and Output” 

> Output file specification Table 5-12 

» Output file specification (append) 

> Diagnostic file specification 

>> Diagnostic file specification (append) 

X Output file and diagnostic file specification 

XX Output file and diagnostic file specification (append) 


You can literalize a character by preceding it with the Shell escape character, 3 (Option- 
D), or by including it within the quotation symbolsor \...\. The escape 
character, 8, quotes a single character only; the other quotation symbols may be used to 
quote part or all of a word. These symbols are described in Table 5-8. 


■ Table 5-8 Quotes 

Quote Description 


'...' “Hard quotation marks”: Take the enclosed string literally—no 

substitutions occur. The quotation marks are removed before 
execution. 

"..." “Soft quotation marks”: Take the enclosed string literally, 3c, variable 

substitutions, and command substitutions occur. The quotation marks 
are removed before execution. 

/.../ or \... \ Regular expression quotation characters: Normally used to enclose 

regular expressions. Take the entire string literally, including the 
quotation characters—the / or \ characters are not removed. Variable 
substitutions and command substitutions occur.and 3 have 
their usual meanings—however, they are not removed. 


Single quotation marks, double quotation marks, and 3 are removed before parameters 
are passed to programs (unless they are themselves enclosed in quotation marks). For 
example, here are two ways you might define an AddMenu that compiles a C program in an 
active window: 

Wrong: AddMenu Extras "C Compile" C "{Active}" 

Right: AddMenu Extras "C Compile" *C "{Active}"’ 
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The first example won’t work because the {Active} variable will be expanded when the 
menu is added (it should be expanded when the menu item is executed). The second 
example is correct—when the AddMenu command is executed, the single quotation marks 
defeat variable expansion; they are then stripped off before the item is actually added. 
The double quotation marks remain in case the pathname of the active window happens 
to contain any special characters. 

♦ Note: When quoting spaces (as in filenames), you’ll usually use double quotation marks 
(soft quotes) to permit variable and command substitution. 

Slashes (or backslashes) are used to pass regular expressions as parameters to commands, 
without filename expansion occurring. For example, 

Search /proc=/ Sample.p 

This command searches the file Sample.p for any string beginning with the characters 
“proc”. (See “Pattern Matching” in Chapter 6 and the description of the Search command 
in Part II.) 
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■ Table 5-9 Special escape conventions 


Symbol Escape convention 

dc Escape character: Take the single character c literally. The four escape 

conventions that follow are exceptions to this rule. 

3Retum dRetum is discarded, allowing you to continue a command onto the 

next line. 

9n Inserts a return character. 

9t Inserts a tab character. 

9f Inserts a form feed character. 


How commands are interpreted 


When you send text to MPWs command interpreter (by pressing the Enter key or the 
equivalent), the following sequence of steps is performed: 

1. Alias substitution. 

2. Evaluation of control constructs. (This means that control constructs can’t be 
produced by command substitution but can have aliases.) 

3. Variable substitution, command substitution. All variables (unquoted or quoted with 

/.../, or \ ...\) are replaced with their value. All commands enclosed in'...' 
(unquoted or quoted with/.../, or \...\ ) are replaced with their output If the 
ellipsis character (Option-semicolon) is found, Commando is executed and the 
command is replaced by the output of Commando. 

4. Blank interpretation. After variables and commands have been substituted, the 
command text is divided into individual words separated by blanks. A blank is an 
unquoted space or tab. 

♦ Note: The following symbols are normally considered separate words, whether or 
not they are set off by blanks: 

; I II && ( ) <>»>>>... 

Within expressions (used with If and Evaluate), all operators are considered 
separate words, unless they are quoted. See “Structured Commands” in 
this chapter. 
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5. Filename generation. A word that contains any of these unquoted characters 
? [ * + « 

after variable substitution is considered a filename pattern. The word is replaced with 
an alphabetically sorted list of the filenames that match the pattern. (If no filename is 
found that matches the pattern, an error results.) 

6. Input/output redirection. Because this step is performed last, variable substitution, 
command substitution, and filename generation can all be used to form the filenames 
used in I/O redirection. 

7. Execution. 

You can suppress any part of this process by using quotation symbols as described in the 
previous section. Remaining single and double quotation marks are removed prior to 
execution. 
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♦ What went wrong? 


If you ever wonder why a command line doesn’t work, refer back to this section 
to study the order of command interpretation. You may use the {Echo} variable to 
examine how the Shell is interpreting your command. Use the command 

Set Echo 1 

With {Echo} defined, the command lines will be echoed to standard output after 
they are interpreted by the Shell. 

The command Parameters is also useful for finding out which parameters will be 
passed to the command. Parameters writes its parameters to standard output. 
This command is especially handy when you want to experiment with quoting. For 
example, try the following commands: 

Parameters = 

f parameters will be all the files in current directory 
Parameters "=" 

# parameter will be the = character 
Parameters "{Commands}" 

# Enclosed in soft quotation marks, the 
variable will be expanded 

Parameters '{Commands}' 

# Enclosed in hard quotation marks, the parameter 
will be the string {Commands} 

Parameters 'date* 

# the output of date will be passed as multiple 
parameters 

Parameters "'date'" 

# the output of date will be passed as one parameter ♦ 


152 


MPW 3.0 Reference 







Structured commands 


Structured commands (listed in Table 5-10) override the normal sequential execution of 
commands. They can be used interactively and within scripts. They may be nested to any 
depth, subject to a limitation on stack space. The entire structured command is read 
before execution begins. All structured commands are built into the MPW Shell. 

A Warning After the Shell “executes” an opening parenthesis or the opening word 
of a Begin, If, For, or Loop command, it will not execute any 
subsequent commands until a matching closing parenthesis or End 
word is encountered. While it is waiting for the end of the command, 
the status panel of the Worksheet window will contain the left 
parenthesis character, (, or the command name. You can abort the 
entire structured command by typing Command-period, a 

The status value for a structured command is the status of the last command executed 
within the structured command (except for the Exit command, which lets you set your 
own status value). 

Expressions (used in If, Break, Continue, and Exit) are defined later in this chapter. 
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■ Table 5-10 Structured commands 

Command_Description 


( command... ) Parentheses are used to group commands for conditional execution, 
pipe specifications, and input/output specifications. 


Begin...End 

Begin 

command... 

End 

If... Else... End 

Like parentheses, Begin and End group commands for conditional 
execution, pipe specifications, and input/output specifications. 

if expression 
command... 

[Else it expression 
command...]... 

[Else 

command...] 

End 

For...End 

The command If...Else...End executes the commands following the 
first expression whose value is true (that is, nonzero and non-null). At 
most one of the lists of commands is executed. If none of the 
commands is executed, If returns a status value of 0. 

For name in word... 
command... 

End 

Loop...End 

The command For...End executes the enclosed commands once for 
each word from the “In word...” list. For each iteration, a variable of 
the form { name} represents the current value from die word... list 

Loop 

command... 

End 

Break 

This command repeatedly executes the enclosed commands. The 

Break command is used to terminate the loop. 

Break [ If expression ] 

The command Break terminates execution of the immediately 
enclosing For or Loop. If the expression is present, the loop is 
terminated only if the expression evaluates to true (nonzero and non¬ 
null). 

(Continued) 
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■ Table 5-10 (Continued) Structured commands 


Command Description 


Continue continue [ If expression ] 

The command Continue terminates this iteration of the immediately 
enclosing For or Loop and continues with the next iteration. If the 
expression is present, the continue is executed only if the 
expression evaluates to true (nonzero and non-null). 

Exit Exit [ number] [ If expression ] 

The command Exit terminates execution of the script in which it 
appears. If number is present, it is returned as the status value of the 
script; otherwise, the status of the last command executed is 
returned. If the expression is present, the script is terminated only if 
the expression evaluates to true (nonzero and non-null). (You can also 
use Exit interactively to terminate execution of all previously entered 
commands.) 


The return characters in the command definitions above are significant; a return must 
appear at the end of each line, as shown above, or it must be replaced by a semicolon (;). 

The following keywords are recognized when they appear unquoted as the first word of a 
command: 

Begin For If Else Loop End Break Continue Exit 

The keyword “In” is recognized when it appears unquoted following For; the keyword “IT 
is recognized when unquoted following Else, Break, Continue, and Exit. These keywords 
are not considered special in other contexts and need not be quoted. 

♦ Note: These keywords cannot be produced as a result of variable substitution or 
command substitution. 

You can apply conditional execution (&& and 11), pipe specifications (I), and 
input/output specifications (<, >, », >, >>, X, and XX) to entire structured 
commands (that is, to Begin...End, If...Else...End, For...End, and Loop...End, and to 
commands within parentheses). 
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The operator should appear following the End or closing parenthesis. For example, you can 
collect the output of a series of commands and redirect it as follows: 

Begin 

Echo Good day 
Echo Sunshine 
End > OutputFile 

Input/output specifications are discussed later in this chapter. Each of the structured 
commands is described in detail in Part n. 


Control loops 

The For and Loop commands are used for looping. 

The For...End command executes the enclosed commands once for each word in the “In 
word...' list The current word is assigned to variable name, so you can reference the 
current word by using the Shell variable notation [name]. For example, 

For File In =.c 

C "{File}" ; Echo "{File}" compiled. 

End 

The Loop command provides unconditional looping, so you’ll need to use the Break or 
Exit commands to terminate the loop. You can use the Continue command to continue 
with the next iteration. 

For example, the script below runs a command several times, once for each parameter: 

#♦# Repeat — Repeat a command for several parameters ### 

# 

# Repeat command parameter™ 

# 

# Repeat command once for each parameter in the parameter 

# list. Options can be specified by including them in 

# quotes with the command name. 

# 

Set cmd "{1}" 

Loop 

Shift 

Break If {#} == 0 
{cmd} "{1}" 

End 

In this example, the Shift command (explained in the next section) is used to step through 
the parameters, and the Break command ends the loop when all the parameters have been 
used. Using the script Repeat, you could compile several C programs, with progress 
information, using the command 

Repeat *C -p' Sample.c Count.c Memory.c 
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Processing command parameters 

In addition to the commands introduced in Table 5-10, there are several other commands 
that are highly useful in scripts. You can use the following commands to display or modify 
parameters: 

Echo [ parameters... ] Writes its parameters, separated by blanks and 

terminated by a return, to standard output 

Parameters [ parameters... ] Writes its parameters, including its name, to 

standard output. One parameter is written per 
line, preceded by the parameter number in 
braces and a space. A return is written following 
die last parameter. 

For example: 

Parameters 1 2 "3a 3b" 

will output 

{0} parameters 

{ 1 } 1 

{ 2 } 2 

(3) 3a 3b 

Shift [ number] Renames the parameters by subtracting number 

from the parameter number; that is, parameters 
number +1, number +2, and so on are renamed 
1,2, and so on. If number is not specified, the 
default value is 1. The variables {1}, {2}...{n}, {#}, 
{Parameters}, and {"Parameters"} are all 
affected. Shift does not affect parameter {0} 

(the command name). 

See the Hints box “What Went Wrong?” in the previous section, “How Commands Are 
Interpreted,” for some suggestions on using Echo and Parameters to troubleshoot 
reluctant command lines. For an example of how the various structured commands can 
work together, see “Sample Scripts” at the end of this chapter. 


Expressions 

Expressions are used in the If, Break, Continue, and Exit commands. They’re also used in 
the Evaluate command, which returns the result of an expression. 

Table 5-11 lists the expression operators in order of decreasing precedence. Some 
operators have more than one representation; these equivalent symbols are listed on a 
single line. Groupings indicate operators of the same order of precedence. 
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Table 5-11 Expression operators in order of decreasing precedence 


Operator 


Operation 

i. 

(,expr) 


Expression grouping 

2. 

- 


Unary negation 


- 


Bitwise negation 


t 

NOT -i 

Logical NOT 

3. 

* 


Multiplication 


■+ 

DIV 

Division 


% 

MOD 

Modulus division 

4. 

+ 


Addition 


- 


Subtraction 

5. 

« 


Shift left 


» 


Shift right 

6. 

< 


Less than 


<= 

< 

Less than or equal to 


> 


Greater than 


>= 

> 

Greater than or equal to 

7. 

== 


Equal 


1 = 

<> * 

Not equal 




Equal pattern (regular 
expression) 


! ~ 


Not equal pattern 
(regular expression) 

8. 

& 


Bitwise AND 

9. 

A 


Bitwise XOR 

10. 

1 


Bitwise OR 

11. 

&& AND 

Logical AND 

12. 

1 1 OR 


Logical OR 


All operators group from left to right. You can use parentheses to override the operator 
precedence. Null or missing operands are interpreted as zero. The result of an expression is 
always a string representing a decimal number. Relational operators return the value 1 when 
the relation is true and the value 0 when the relation is false. 
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Logical operators: The logical operators!, NOT, &&, AND, | |, and OR interpret 
operands of value 0 or null as false; and they interpret nonzero, non-null operands as true. 

Numbers may be 

■ decimal 

■ hexadecimal, beginning with either $ or Ox 

■ octal, beginning with zero 

■ binary, beginning with Ob 

Every expression is computed as a 32-bit signed value. Overflows are ignored. 

String operators: The operators ==, !=, =-, and!~ compare their operands as strings. All 
others operate on numbers. 

♦ Note: The {CaseSensitive} variable does not apply to the string operators. 

Comparing text patterns: The =~ (equal pattern) and!~ (not-equal pattern) operators 
are like == and != (which compare two strings), except that =- and!~ are used for 
comparing a string with a text pattern. The right side is a regular expression against which 
the left-side operand is matched. For example: 

If ”{1}" !~ /=•[acp]/ 

Echo Filename must end with .a, c, or .p 

End 


♦ Note: The regular expression in the above example must be enclosed in the regular 
expression quotation symbols, /.../. See Chapter 6 for more information about regular 
expression syntax. 


If the regular expression contains the tagging operator ®, then, as a side effect of 
evaluating the expression, Shell variables of the form {® n} containing the matched 
substrings are created for each tag operator in the expression. (For an example, see the 
implementation of a wildcard rename command under the description of the Rename 
command in Part II.) 
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Use of special characters: Within expressions in the If, Break, Continue, Exit, and 
Evaluate commands, the following Shell operations are disabled: 

■ Filename generation 

■ Conditional execution (11 and &&) 

■ Pipe specifications (I) 

■ Input/output specifications (>, », >, >>, <, X, and XI) 

This allows the use of many expression operators that would otherwise have to be quoted. 
In the case of If commands, the conditional execution or I/O specification should come 
after the End word. For other commands that contain expressions, you can specify 

conditional execution or I/O redirection by enclosing the command in parentheses. For 
example, 

(Evaluate {1} + {2}) > Errors 


Redirecting input and output 


All built-in commands, scripts, and tools are provided with three open files: standard 
input, standard output, and diagnostic output (Figure 5-2). By default, standard input 
comes from the console (the window where the command is executed). Standard output 
and diagnostics are returned to the console immediately following the command. 
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■ Figure 5-2 Standard input and output 



Standard 

output 


Standard 

input 


Resource Compiler 
(Rez) 


/ 




\ 


—k 

Diagnostic 

output 


You can override these default assignments with the <, >,», > >>, Z, and ZZ 
symbols described in Table 5-12. Note that input and output specifications are 
interpreted by the Shell; they are not passed to commands as parameters. You can use 
parentheses (or the Begin and End commands) to group commands for input/output 
specifications. 


■ Table 5-12 

I/O redirection 

Symbol 

Override operation 

< name 

Standard input is taken from name. 

> name 

Standard output replaces the contents of name. The file name is created 
if it doesn’t exist. 

» name 

Standard output is appended to name. The file name is created if it 
doesn’t exist. 

> name 

Diagnostic output replaces the contents of name. The file name is 
created if it doesn’t exist. 

>> name 

Diagnostic output is appended to name. The file name is created if it 
doesn’t exist. 

Z name 

Standard output and diagnostic output replace the contents of name. 

The file name is created if it doesn’t exist. 

ZZname 

Standard output and diagnostic output are appended to name. The file 
name is created if it doesn’t exist 
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Files and windows are treated identically; when given a name, the system looks first for an 
open window. Input and output can also be applied to selections: 

■ § indicates the current selection (in the target window). 

■ name.% indicates the current selection in window name. 

From the point of view of a command running within the Shell environment, input always 
comes from the standard input file and output goes to the standard output file. The 
command doesn’t need to know whether standard input happens to be text from a file, a 
window, or a selection, or is typed in from the keyboard. For example, in the statement 
Program > OutputFile 

the string “> OutputFile” is interpreted by the Shell and is not passed as a parameter to the 
command—this process is completely invisible to the command. 

I/O specifications also apply to scripts. The standard input, standard output, and 
diagnostic output files provided to a script become the defaults for commands in the 
script. 

In addition to the sections later in this chapter, you’ll find more on input and output in 
“Standard I/O Channels” in Chapter 12. 


Standard input 

By default, standard input is supplied by typing text and pressing Enter, or by selecting 
text that is already on the screen and pressing Enter. You can redirect standard input with 
the < operator. Note, however, that most commands that read standard input also accept 
a filename parameter. For example, the following two commands have the same result: 

Catenate < Sample.c 
Catenate Sample.c 

The Alert command reads from standard input if no message is supplied as a parameter to 
the command, but Alert doesn’t accept filenames as parameters. Thus input redirection is 
the only way to cause Alert to read input from a file. 

Alert Errors # Display Alert box containing the word Errors 

A ^ ert < Errors # Display Alert box containing the contents 

# of the file Errors. 

Many commands, including the Assembler and compilers, optionally read standard input 
to allow input to be read from a pipe (I) or entered interactively, as explained in the next 
section. 
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Terminating input with Command-Enter 

Many commands read from standard input if no filename is specified. For example, if you 
execute the command 

Asm 

the Assembler will begin reading from standard input—that is, you can enter text to 
standard input, and the Assembler will process each line as you enter it 

You can repeatedly enter text to a program that reads standard input by typing or 
selecting text and pressing Enter. You indicate end-of-file by holding down the Command 
key and pressing Enter (or Command-Shift-Retum). For example, after you execute the 
command 

Catenate » {Worksheet} 

the Catenate command will be running (its name will appear on the status panel at the 
bottom of the window). You can now enter data from the keyboard or select and enter 
text from various windows, and all of it will be concatenated to the Worksheet window. 
Pressing Command-Enter indicates end-of-file and terminates the command. 


♦ Power techniques using standard input 

There are many ways you can save time and effort by running tools from 
standard input. 

For example: Suppose you want to compose a file from parts of other files—and 
there are ten sections that you want to use in your new file. Normally you'd 
cut and paste ten times. However, you could also run Catenate from standard 
input with the command 
Catenate » MyComposedFile 

While Catenate is running, you can open the different source files, select the 
desired sections, and press Enter. Each time you press Enter, that selection is 
appended to the file MyComposedFile. When you have finished, press 
Command-Enter. 

Many times it's convenient to quickly type a few lines of code in the 
Worksheet and then interactively compile (or Rez, using the resource 
compiler) those lines to test out syntax or examine compiler behavior. You'll 
find that you can speed up many tasks and increase confidence with quick 
tests by running tools interactively and using selections as input. ♦ 
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Standard output 


By default, standard output appears in the window in which the command was executed 
(that is, the console) immediately following the command. When commands are executed 
from menus, standard output appears following the selection in the active window. You 
can redirect standard output with the > and » operators. For example, the Catenate 
command 

Catenate Filel File2 > CombinedFile 

concatenates File2 to Filel—but instead of appearing in the active window, output is 
sent to the file named CombinedFile. If the window CombinedFile is open on the 
desktop, its contents are overwritten. Otherwise, the file CombinedFile is replaced (or 
created if it doesn’t exist). 

The » operator appends standard output to the end of a selection, window, or file. If 
the named file doesn’t exist, a new file is created. For example, 

Catenate § » AFile 

appends the contents of the current selection in the target window to AFile. (If the 
command was entered in the active window, the current selection is the selection in the 
target window.) You can also specify a selection in a named window: 

Catenate Sample.c.§ » AFile 


Diagnostic output 


By default, a command’s diagnostic output also appears immediately after the command, 
interleaved with standard output. The diagnostic output of commands executed from 
menus appears following the selection in the active window. You can redirect diagnostic 
output exactly as you redirect standard output, except that you use the operators > (to 
replace filename) and >> (to append to filename) in place of > and ». You may find it 
useful to have all error reporting appear in a separate window set aside for that task. For 
example, in Figure 5-3, the Assembler has been run and error and progress information has 
been appended to a window called “Errors.” 
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Figure 5-3 Redirecting diagnostic output 


■ 



Often it is useful to redirect both standard output and diagnostic output to the same file, 
using the summation operators X (to replace filename ) or XX (to append to filename). 
The example used in Figure 5-3 might then be written in the Worksheet like this: 

Asm -a Sample.a XX SampleTest 

Then both the output of Sampler and its diagnostics, including any errors, would be 
appended to a file named HD:MPW:AExamples:SampleTest. 


Pseudo-filenames 

Pseudo-filenames are a set of device names that you can use in place of filenames; 
however, they have no disk files associated with them. Any command can open a pseudo- 
filename as a file. These device names are most commonly used for I/O redirection. 

Table 5-13 shows the available pseudo-filenames. 
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■ Table 5-13 

Pseudo-filenames 

Pseudo-filename 

Description 

Dev:Console 

Always refers to the current console device. The console is the default 
source of input and the default destination of output—that is, the 
active window where a command is entered and its output displayed. 

Dev:Null 

Null device. If you read from Dev:Null, it immediately returns end-of- 
file. If you write to Dev:Null, output is thrown away. 

Dev:StdIn 

Standard input. 

Dev:StdOut 

Standard output. 

Dev:StdErr 

Diagnostic output. 


Pseudo-filenames are especially useful inside a script if you want to do something like 
sending standard output to the diagnostic output of the script Here are some examples: 

Echo "An error message." » Dev:StdErr 
Echo "HELP !" » Dev:Console 

Dev:Null is useful in scripts when you want to throw away diagnostic output. For example: 
Eject 1 > Dev .-Null 

This command ejects the disk in drive 1; if no disk is in drive 1, the script continues to run 
silently. (Note that you would also need to set {Exit} to 0—see “Variables” earlier in this 
chapter.) 


Editing with the command language 

Almost all menu commands have equivalents in the command language. In most respects, 
there is no difference between the menu commands and their command-language 
equivalents. The primary difference is that with the command language, you enter 
commands in the active (frontmost) window, while an editing command acts on a 
selection in another window. You can explicitly name a window as a parameter to the 
command. If you don’t specify a window, the command acts on the target window. 
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For example, to use command-language techniques to edit the file Sample.a, you must 
first open that file, and then click on another window, such as the Worksheet window, to 
make it the active window. You enter your commands in the active window, as shown in 
Figure 5-4. When you select text in the active window, it’s highlighted in the normal 
Macintosh fashion. In other windows, selected text is indicated by dim highlighting 
(outlining), as shown in the target window in Figure 5-4. 


■ Figure 54 Text highlighted in the active and target windows 

r 6 File Edit Find Mark Window Project Directory Build 



Editing commands generally act on a selection. (The Find command simply creates a 
selection—“DRVR” in this example.) 

The § metacharacter (Option-6) is the current selection character. It signifies the current 
selection in a window. For example, the following command erases from the current 
selection or insertion point in the target window to the end of the window: 

Clear §:«> 

The infinity character, °° (Option-5), is a selection operator that indicates the end of a 
window, as described in Chapter 6. For interactive editing, press Command-Delete to 
clear to the end of a file. 


CHAPTER 5 Using the Command Language 167 




























Defining your own menu commands 


The AddMenu and DeleteMenu commands are for adding and deleting menu items. The 
AddMenu command takes three parameters: the menu name, the item name, and the 
command text. For example, 

AddMenu Find ’Top of Window/U’ ’Find • ’’{Active}”’ 

This command adds a “Top of Window” item to the Find menu, using the keyboard 
equivalent Command-U. When you select the menu command, the corresponding 
commands are executed. (The Top of Window item moves the insertion point to the top 
of the active window.) 

Invoking a user-defined menu Command is the same as entering the command text from a 
window—variable substitution and command substitution are performed normally. Note, 
however, that the text of the menu command is processed twice—once when the 
AddMenu command itself is executed, and again whenever the menu item is executed. 
This means that you have to be especially careful in your use of quotation symbols. The 
mysteries of quoting are explained earlier in this chapter in “Quoting Special Characters,” 
together with further AddMenu examples. You should also pay particular attention to the 
section “How Commands Are Interpreted.” For further information, and more examples, 
see the AddMenu command in Part II. 


Sample scripts 


The following examples use most of the Shell’s features to illustrate how you can extend 
the MPW Shell with your own commands. 
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“AddMenuAsGroup” 

The following script adds an extra feature to the AddMenu command: 

# AddMenuAsGroup - AddMenu, grouping user defined menu items: 

# 

# AddMenuAsGroup [ menuName [ itemName [ command ] ] ] 

# 

# AddMenuAsGroup duplicates the functionality of the AddMenu 

# command, adding a disabled divider before the first user- 

# defined menu items in the File, Edit, and Find menus. 

# 

Unalias 

Set Exit 0 

Set CaseSensitive 0 

If ({#} == 3) AND ("{l}" =~ /File/ OR "{1}” — /Edit/ 3 
OR "{1}" =~ /Find/) 

If 'AddMenu "{1}"' == "" # If this is the first addition 

# in (1), 

AddMenu "{1}" "(-" "" # add the group divider 

End 

End 

AddMenu {"Parameters") 

When adding menu items to the predefined menus, it’s useful to add a disabled dotted 
line item to separate the new menu items from the original ones. The script above 
automatically adds the separator before the first new item in the File, Edit, and Find 
menus, the only predefined menus that an be modified by using AddMenu. If you put this 
script in a file named AddMenuAsGroup, the following alias will override the built-in 
AddMenu command: 

Alias AddMenu AddMenuAsGroup 
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“CC” 


The following script extends the C command by making it possible to compile a number 
of specified files: 

# CC - Compile a list of files with the C compiler 

# 

# CC [options...] [file...] 

# 

# Note that the options and the files may be intermixed, and 

# that all options apply to all the files. The individual C 

# commands are echoed to diagnostic output as they are executed. 

# 

Unalias 
Set Exit 0 
Set CaseSensitive 0 
Set options "" 

Set files "" 

Set exitStatus 0 
Loop 

Break If {#} == 0 

If "{1}" =~ /-[diosuj/ # options with a parameter 

Set options "{options} '{1}' '{2}'" 

Shift 2 

Else If "{1}" =~ /-=/ # other options 

Set options "{options} '{1}'" 

Shift 1 
Else 

Set files "{files} Ml}’" 

Shift 1 
End 

End 

For i in {files} 

C {options} "{i}" II Set exitStatus 1 

End 

Exit {exitStatus} 
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Chapter 6 Advanced Editing 


MPWS EDITING OPERATIONS ARE AVAILABLE AS BUILT-IN COMMANDS, including 
scriptable selections and the use of regular expressions. These commands enable 
powerful find-and-replace functions and make it possible to automate editing 
operations by using scripts. 

Menu commands for editing are described in Chapter 3. The basics of routine 
interactive editing are described in Chapter 4. For a full description of the use of 
the command language, see Chapter 5. Appendix B contains a summary of 
selections and regular expressions. ■ 
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Editing commands 

The command language contains editing commands that duplicate the functions of many 
of the menu commands and provide additional capabilities. The editing commands are 
listed in Table 6-1. (They’re explained in detail in Part n.) 

■ Table 6-1 Built-in editing commands 

Command Description 


Adjust [-c counii [-1 spaced selection [windouh 
Align [-c counii selection [windouh 
Clear [< counii selection [windouh 
Copy [-c counts selection [windouh 
Cut [-c counii selection [windouh 

Find [-c counii selection [windouh 
Format [ option... ] [ window...] 

Mark [ -y I -n ] selection name [windouh 

Markers [-q] [ window] 

Paste [-c couni selection [windouh 

Position [ -c I -1 ] [ window ...] 

Replace [-c counii selection replacement [windouh 
Revert 1-y ][ window...] 

Target name 
Undo [ window] 

Unmark name... window 


Adjust lines in a selection. 

Align text with first line of selection. 

Delete selected text 

Copy selected text to the Clipboard. 

Copy selected text to the Clipboard and 
then delete the selection. 

Find and select text 

Set or view font name, font size, tabs, 
and indents on specified windows. 

Assign the marker name to the range of 
text selection selected in window. 

Print list of all markers associated with 
window. 

Replace selection with the contents of 
the Clipboard. 

Display the position of the selection in 
each specified window. 

Replace selection with replacement. 

Revert window to last saved state. 

Make a window the target window. 

Undo last command. 

Remove the markers) name... from the 
list of markers available for window. 
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If no window parameter is specified, editing commands act on the target window, 
which is the second window from the front. Therefore, to edit the active window, you’ll 
need to switch to another window for entering your commands, or else specify the name 
of the active window in the command line. (The Target command makes a window the 
target window; the Shell variables {Active} and {Target} always contain the full pathnames 
of the current active and target windows.) 

Most editing commands take the following parameters: 

•c count You can specify a repeat count with the -c option; count is the 

number of times the command should be executed. Count may also 
be the infinity character, » (Option-5), which specifies that the 
operation should be repeated as many times as possible. 

selection Most editing commands act on a selection, either the current 
selection in the taiget window or another selection that you 
specify. First, an implicit Find is done to select the specified text. 

TTien the text is modified. The selection syntax is defined in the 
next section. 

window The optional window parameter lets you specify the name of the 
window to be affected by a command without changing the 
position of the affected window. 

A command modifies the selection only if there were no syntactic errors in the selection 
and if all regular expressions were matched. Commands run silently unless an error occurs. 

In addition to the routine editing commands incorporated in the command language, 
MPW includes a number of tools and scripts that are useful for many specialized editing 
tasks. Some of these are listed in Table 6-2. See Part n for detailed information. 


174 


MPW 3.0 Reference 




■ Table 6-2 MPW tools useful for editing 


Editing tools 

Description 

Canon [ option... ] dictionaryFile [ inputFile... ] 

Replace a file’s identifiers with 
canonical spellings given in 
dictionaryFile. 

Compare 

Compare text files. 

Entab [ option...] [file...] 

Convert runs of spaces to tabs. 

FileDiv [ option... ]file 

Divide a file into several smaller 
files. 

line [ number ] 

Find specified line number in a file. 

Matchlt [ option... ] [ window ] 

Match currently selected left 
language delimiter with its mate in 
window. 

RezDet [ option...] resourcefile 

Detect inconsistencies in resources. 

Translate [ option... ] source [destination] 

Convert selected characters. 


Selections 


A selection is a parameter to editing commands; it tells the command what text to select 
A selection may be any of the following: 

■ A line in a file (selected by line number) 

■ A position in a file 

■ A marker 

■ A specific character pattern 

■ A selection that begins and ends with any of the above 

As an example of the selection syntax, consider the definition of the Find command: 

Find [-c count] selection [windoui 

Find takes a selection as an argument and selects the argument text (or sets the insertion 
point). An actual command might take the form 

Find /shazam/ 
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This command finds and selects the first instance of the string “shazam” that appears 
after the current selection. (The slashes are used to enclose a pattern, a special case of a 
selection, as explained below.) No count is specified, so the command is executed once. 
No window name is specified, so the command operates on the target window. 

Table 6-3 shows all of the selection operators. These are more fully explained in the 
sections following the table. 


■ Table 6*3 Selection operators 


Operator 

Type of selection 

Current selection 
§ 

Current selection in the target window (§ is Option-6 
on the keyboard) 

line numbered selections 

n 

Line number n 

In 

Line number n lines after the end of the current 
selection 

\n 

Line number n lines before the start of the current 
selection (j is Option-1) 

Position (insertion point) 

• 

Position before the first character of the file (• is 

Option-8) 

oo 

Position after the last character of the file (°° is 

Option-5) 

A selection 

Position before the first character of selection (A is 

Option-J) 

selection A 

Position after the last character of selection 

selectionln 

Position n characters after the end of selection 

selections 

Position n characters before the beginning of 
selection 

Pattern (characters to be matched) 

/pattern/ 

Pattern (regular expression)—search forward (see 
“Pattern Matching,” below) 

\pattem\ 

Pattern—search backward 

Extended selection 

selectionliselection2 

Both selections and everything in between 

marked selection name 

The name of a marked selection may contain any 
characters except 


§ ! j ( : • ~ A / \ 

Grouping 

( selection) 

Controls order of evaluation 
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A formal definition of selections can be found in Appendix B. 

All of the operators group from left to right, and evaluation proceeds from left to right. 
The selection operators are listed below in order of precedence: 

/ and \ Everything within slashes is taken as a regular expression and 
is evaluated as explained below under “Pattern Matching.” 

( ) Controls the order of evaluation. 

A Indicates position. 

! and j Indicates position (! = after; \ = before). 

: Joins two selections. 

Some examples will illustrate why it’s important to pay attention to the precedence of 
these operators: 

A/begin/ !1 means (A/begin/ )!1 

rather than a ( /begin/ ! 1 ) 

That is, the insertion point is located after the “b” of “begin” rather than 
after the “n.” 

/begin/ : /end/ ! 1 means the selection /begin/ : ( /end/! 1 ) 

rather than the position ( /begin/: /end/)! l 

That is, the character after “end” is included in the selection, as shown in Figure 6-1. 


■ Figure 6-1 A selection specification 



File Edit Find Mark tilindom Project Directory 


Find /begin/:/end/!1 


HD:MPlD:Ulorksheet 


Build 


MPW Shell 


HD:MPLU:EKamples:PEKamples:Memory.p 


END 


SetPort <SavePort>; 

END; 

DRUROpen := NOErr; 


FUNCTION DRURCIose<ctiPB: PormBIkPtr; dCtl: DCtIPtr): OSErr; 


BEGIN 


IF dCtI * .dCtl«uindoor <> NIL THEN 
BEGIN 


END:! 


DisposeUindour 04indowPtr<dCtl* .dCt lUindow) >; 
dCtr dCtlUindour := NIL: 


DRURCIose := NOErr; 
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Current selection (§) 

The current selection character, § (Option-6), always indicates the current selection in a 
window. If no window is specified, § indicates the current selection in the target window. 
For example, consider the windows shown in Figure 6-2. 


■ Figure 6-2 Selections in two windows 


Project Directory Build 



HD;MPU»:EKample$:PEnampies:Memory.p 


wRect: Red; 

myUindow: UindowPtr; 

BEGIN 

IF dCtl“.dCtlUindow = NIL THEN 
BEGIN 

GetPort CSavePort); 

myUindow := GetNewUindowCRsrclDCdCtl),niI,P0INTER<-1))• 

xr..- , ^?^ e li < " ylJind0 “ r Uind0,, ” <ind := <*Ctl*.dCtlRefNum; '{ show a d 
dCtl .dCtlUindon : = muUindow: < let the desk eanager know too ) 4 

beapGrouj := Maxflem (heopGrow ) ;| 

SetPort CSavePort); 

END; 

DRUROpen := NOErr; 

END; 


The command 
Replace § 3n 

would replace the current selection in the target window with a single return (newline) 
character. (“9n” is a special code for inserting a return—see “Inserting Invisible 
Characters” later in this chapter.) 

Note that the current selection is a dynamic quantity—it’s determined by the last 
subexpression evaluated and thus represents the current state of a selection as it’s being 
calculated. For example, consider the command 

Find /if/:§!l:§!l 
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At various points in the evaluation of the search string Vif/:§!1:§!1”, the current selection 
(§) has the following different values: 

Before calculation The pre-existing selection in the target window 

After “/if/” “if” 

After 7if/:§!l” All characters from “if” to (and including) the first 

character after the “if 

After “/if / : §! 1: §! 1” All characters from “if to (and including) the first 

two characters after the “if 


Selection by line number 

If you give a number unquoted by slashes as a selection, it is taken to be a line number. 
This may be an absolute line number or a number of lines relative to the current selection. 
For example, to select line 3 of a file, you’d use the command 

Find 3 

This expression is equivalent to 
Find '3* 

but 

Find 3 or Find * 3 * 

is not equivalent to 

Find /3/ or Find \3\ 

The exclamation mark and inverted exclamation mark (! and j) specify the number of lines 
after or before the current selection. Thus, the command 

Find !3 

selects a line that is 3 lines beyond the current selection. Note that the !n notation 
specifies a line relative to the end of the current selection (that is, n lines past the line 
containing §A); \n specifies a line relative to the start of the current selection (n lines 
before the line containing A§). 
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Position 


A position is a special case of selection. Position means the location of the insertion 
point only. The A character (Option-J) is used to convey position relative to a selection. 
For example, consider the commands 

Find 3 
Find A3 
Find 3A 

The first Find command selects the entire third line in the target file. The Find A3 and 
Find 3 A commands place the insertion point at the beginning and at the end of the third 
line, respectively. 

You can also use the! and j operators to specify a position that’s a given number of 
characters from a selection: selectiorin specifies a position n characters after selection, 
and selection,\n specifies a position n characters before selection. 

Note that this leads to two different uses of the! and \ operators, as in the following 
example: 

Find !4!4 

The first *!4” indicates a selection that’s 4 lines beyond the current selection; the second 
“!4” indicates the position that’s 4 characters beyond the end of that selection. 

You can specify other positions in a file with the following special notation: 

• (Option-8) Position preceding the first character in a file 

°o (Option-5) Position following the last character in a file 


Markers 

A marker is a selection that has been given a name. A marker may be used as a selection 
variable. You can mark as many selections and insertion points as you wish. You can create 
markers directly by selecting text in a window and then clicking the Mark command in the 
Mark menu. See “Mark Menu” in Chapter 3 for more information on the interactive use of 
markers. This section describes the general behavior and programmatic use of markers. 
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Behavior of markers 

Markers may be as simple as a position in a window, but more often a marker names a 
range of positions. Markers have the special attribute of being able to remember their 
assigned position(s) even when you’re making editing changes all around them. For 
example, typing before marked text has the effect of moving both the text and its 
associated marker toward the end of the window. Editing “inside” the range of a marker 
will either increase or decrease the range of the marker, depending on whether the editing 
was an insertion or deletion, respectively. 

Markers are “sticky.” For example, if an insertion point is marked and you enter text at 
that point, everything you type will be added to that marker. 

If you delete the text encompassing a marker the marker will also be deleted. For example, 
if the string “xyz” is deleted and the character “y” is marked, the “y” marker will be 
deleted. However, if the string “xyz” itself is marked as “y,” deleting the string “xyz” will 
result in marker “y” being reduced to an insertion point 

Markers are associated with individual windows. When you switch between windows, the 
Mark menu is updated to reflect the markers of the new active window. 

Markers are persistent. They are saved in the resource fork of the file you are editing, just 
like font, tab, and other information about the window. However, markers are not saved 
to the Clipboard. Thus, if you cut a marked region and paste it somewhere else, the 
marker will be lost. 

Markers are case sensitive. A marker named *Y” is different than a marker named “y.” 

Programmatic use of markers 

You can create or delete Markers programmatically by using the following three Shell 
commands: 

Mark [ -y I -n] selection name [ windou] Assign the marker name to range of text 

selection selected in window. 

Markers l -q ] [ window] Print a list of all markers associated 

with window. 

Unmark name. . .window Remove the markers) name. .. from the 

list of markers available for window. 

For example, to mark the currently selected text in the target window with the name 
“Function B” and to replace any previous marker of that name, you would type 

Mark -y § 'Function B' 
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The new marker name will appear in the Mark menu. You might remove the marker later by 
using the Unmark command: 

Unmark 'Function B' "{Target}" 

This command would remove that marker from the target window. 

To use markers as selections, just type the marker name. For example, 

Find george 

For further details on the Shell commands for markers, see Part II. 


♦ Automatic Selection 

You'll find many ways to use markers for automatic selections. For example, to 
automatically select the output of a script for a user, you could use a script 
similar to this: 

Mark §A X #Mark the start of output 
Make #Run your Make command 

Find X #Select the output of Make ♦ 


Pattern 


A pattern may be either a literal text pattern or a regular expression (defined in the next 
section). You specify a pattern between the /.../ and \...\ delimiters. Forward slashes 
indicate a search forward, and backslashes indicate a search backward. A forward search 
begins at the end of the current selection and continues to the end of the file. A backward 
search begins at the start of the current selection and continues to the beginning of the 
file. For example, the command 

Find /myString/ 

searches forward for the literal expression “mystring.” (Recall that to specify case- 
sensitive pattern matching, you need to set the Shell variable {CaseSensitive}, or select the 
"Case Sensitive” menu item.) 
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Extending a selection 

A colon is used to join two selections. For example, 

Find /begin/:/end/ 

This command selects “begin,” “end,” and everything in between. (See Figure 6-1.) 
Compare this command with 
Find /begin~end/ 

which looks for a begin-end pair on a single line. 


Pattern matching (using regular expressions) 

Regular expressions are a shorthand language for specifying text patterns. Regular 
expressions ate used in editing commands, in the Search command (which searches one or 
more files for occurrences of a pattern), and in If and Evaluate expressions following the 
=- and!- operators. Most of the regular expression operators may also be used in filename 
generation. 

Regular expressions are always used within the pattern delimiters /.../ or \ ...\. 

A special set of metacharacters, called regular expression operators, is used in regular 
expressions (and in filename generation). The regular expression operators are listed in 
Table 6-4. 
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■ Table 6-4 Regular expression operators 


Operator 

Meaning 

C 

Any charaaer matches itself (unless it’s one of the 
special characters listed below) 

d c 

Defeat the special meaning of the following character 
(c is taken literally) except 
dn = return 

5t = tab 
df = formfeed 

t t 

Literalize enclosed characters 

it it 

Literalize enclosed characters, except d, {, and ' 

7 

Any single character (other than a Return) 


Any string of 0 or more characters that does not contain 
a Return 

[character...] 

Any character in the list 

[-. character ...] 

Any character not in the list (— i is Option-L on the 
keyboard) 

regularExpr* 

Regular expression 0 or more times 

regularExpr+ 

Regular expression 1 or more times 

regularExpr«n» 

Regular expression n times («is OptionA; » is 

Option-ShiftA) 

regularExpr«n,» 

Regular expression n or more times 

regularExpr«n\, rz 2 » 

Regular expression «i to n 2 times 

(regularExpr) 

Grouping 

(regularExpr)® n 

Tagged regular expression (where 0 < n < 9) 

regularExpr 1 regularExpr 

regularExpr followed by regularExpr 

•regularExpr 

Regular expression at the beginning of a line 

regularExproo 

Regular expression at the end of a line 

These characters are considered special in the following circumstances: 

a 

Special everywhere except within single quotation 
marks 0...') 

?-*+[«() 

Special anywhere except within [...],and 


Special only after a right parenthesis,) 

• 

Special as the first character of an entire regular 
expression 

oo 

Special as the last character of an entire regular 
expression 

/ \ 

Special if used to delimit a regular expression 

-1 

Special only after a left bracket, [ 


Special in brackets, except immediately following 
a left bracket, [ 
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Their precedence (from highest to lowest) is as follows: 

1 . ( ) 

2 . ?-* + []« ® 

3. concatenation 

4. • °° 

A formal definition of regular expressions an be found in Appendix B. The rest of this 
section describes the use of regular expressions for describing selections. 


Character expressions 

In the simplest case, regular expressions consist of literal characters enclosed in slashes. 

For example, 

/what the ?/ 

Notice one compilation, however: if the literal character happens to be one of the 
regular expression operators (such as *?”), it will be specially interpreted rather than taken 
as a literal character. If you want to specify a literal character that happens to have a 
special meaning within the context of regular expressions, you’ll have to precede it with 
the esape character, 3, or enclose it in quotation marks. The character d has the effect of 
“literalizing” the character that follows it. For example, to find the literal expression given 
above, you would use one of the following commands: 

Find /what the d?/ 

Find /what the '?'/ 

Find /'what the ?'/ 

You could also use double quotation marks, that is 
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Wildcard operators 

In addition to literal characters, regular expressions can include the operators ?, = 
(Option-X), and [ ], which are used as follows: 

? Any character other than a Return 

= Any string not containing a Return, including the null string 

(this is the same as ?*) 

[characterLisH Any character in the character list (as defined below) 

[-. characterList] Any character not in the list 

These operators are also used as wildcards in filename generation. (You can also use the *, 
+, ?, ~ [...], and «...» operators in filename generation—see “Filename Generation” in 
Chapter 5.) 

A character list is an expression consisting of one or more characters enclosed in brackets 
([...]). It matches any character found in the list The case sensitivity of characters in the 
list is governed by the {CaseSensitive} variable. A list may consist of individual characters 
or a range of characters, specified with the minus sign (-). For instance, the following two 
commands are equivalent 

Find /[ABCDEF]/ 

Find /[A-F]/ 

You can also mix the two notations: 

Find /[0-9A-F$]/ 

♦ Note: This command specifies any of the characters 0 through 9, A through F, and 
$. To specify the ] or - character, place it at the beginning of the list or literalize 
it with the escape character, 9. 


The negation symbol, -* (Option-L), lets you specify any character not in the list For 
example, 

Find /[-A-Z]/ 

This example specifies all characters except the letters A through Z. (To specify the i 
character itself, place it anywhere in the list other than the beginning, or literalize it by 
preceding it with the escape character, 3.) 
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Repeated instances of regular expressions 

The asterisk character (*) matches zero or more occurrences - of the immediately 
preceding regular expression. The plus sign (+) matches one or more occurrences of an 
expression. For example, the command 

Find /[0-9]+/ 

will find any string of one or more digits. 

You can also specify an expression that occurs an explicit number of times by using the 
«n» notation: 

regularExpr*n> Regular expression n times 

regularExpr*n,‘ Regular expression at least n times 

regularExpnn\,ni * Regular expression at least n\ times and at most ni times 

For example, 

Replace -c /' '«4,»/ dt 

This command finds any string of four or more spaces and replaces it with a tab. 

(The -C °° option specifies a repeat count of “infinity”; that is, it replaces all occurrences 
of of the selection to the end of the document) 
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Tagging regular expressions with the ® operator 


The ® (Option-R) operator tags a regular expression between parentheses. This operator 
is useful with the Replace command, for example, in reformatting tables of data. Consider 
a table with two columns of numbers separated by spaces or tabs: 


123 456 

123 456 

123 456 

123 456 

.. .andso on 


The following Replace command switches the order of the two columns, which are 
separated by one tab: 

Replace -c » /([0-9]+)®l[ 9t] + ( [0-9]+)®2/ *®2 ®1 • 


Translated into English, this expression means 
[ o - 9 ] + Match one or more characters in the set “0” to “9”. 

([ 0 - 9 ] +) ® l Remember that selection (the expression enclosed in 

parentheses) as ®1. 

[ 9t] + Next, match at least one space or tab. 

( t o - 9 ] +) ® 2 Then match one or more characters in the set “0” to “9” and 

remember it as ®2. 

' ®2 ®i * Finally, replace the whole matched string with what was 

remembered as ®2, a space, and what was remembered as <! 


♦ Note: The quotation symbols are stripped off, as explained under “Quoting Special 
Characters” in Chapter 5. 


After this sequence is executed, the table will look like this: 


456 123 

456 123 

456 123 

456 123 

. ..and so on 
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Matching a pattern at the beginning or end of a line 


In the context of regular expressions, the • metacharacter (Option-8) means that the 
subsequent expression must be matched at the beginning of a line. For example, the 
regular expression 
/ •main/ 

will match a line that begins with “main” but not a line that begins with “space main”. The 
beginning of a line is either the first character after a return or the first character of the 
file. 

Likewise, the «> metacharacter (Option-5) means that the previous expression must be 

matched at the end of a line. The regular expression 

/main«>/ 

will match a line that ends with “main” but not a line that ends with “main space ”. The end 
of a line is either the last character of a line prior to the return, or the end of the file. 

Notice that • and have another meaning within selections. Within a pattern, they 
indicate the beginning and end of a line. Within a selection, they indicate the beginning 
and end of the file. 


Inserting invisible characters 

You can use the Shell escape character, 8, to insert the following special characters in text: 


8n 

return 

at 

tab 

df 

form feed 


For more information on the escape character, see “Quoting Special Characters” in 
Chapter 5. 


CHAPTER 6 Advanced Editing 189 










Note on forward and backward searches 


Forward and backward searches aren’t always completely symmetrical. For example, 
consider the command 

Find /?*/ 

This command finds zero or more occurrences of any character other than a return. The 
first time you execute this command, some range of characters will be selected if the 
current selection is not at the end of a line. However, in subsequent invocations, the 
selection will stick at the end of the line and only an insertion point will be left at the end 
of the line. This is because the * metacharacter matches zero occurrences and the search 
starts with the character following the current selection—in this case, the insertion point 
preceding a return. A backward search of the form 

Find \?*\ 

will never stick at the beginning of a line. This is because a backward search begins with 
the first character to the left of the current selection and so has the effect of jumping over 
a return after encountering it. 
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♦ Solving selection difficulties 

What If a selection expression doesn't select what you intended? Ask yourself 
questions like these: 

■ Am I quoting special characters? 

For example, the 

*C 

character is special. If you are searching for this character, then you 

must use 

•3C 

■ Do I remember the definitions of special characters? 

Review the special character definitions in Appendix B. 

■ Are my precedence and usage correct? 

Consider the slightly different syntax of these two Find commands: 

Find •:/main/ 

This tells MPW to select everything from the beginning of the file until the 
first occurrence of the word ‘main' 

Find /»main/ 

This tells MPW to select the next occurrence of the word 'main' at the 
beginning of a line. 

■ Do the individual pieces select what I intended? 

Break the difficult expression down into small parts. Try each part separately 
to make sure that it does what you want. Then add each new, tested part 
to create more complicated expressions. ♦ 


Some useful examples 

This section shows some examples of the complex use of regular expressions. 
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Transforming DumpObj output 


The DumpObj command, described in Part II, formats the contents of an object file. This 
example shows how to transform a DumpObj listing, such as the following, back into valid 
assembly code. 


000000 

4EBA 

06F8 

'N. . . 

V 

JSR 

*+$06FA 

6004282A 

000004 

4E5A 

04EA 

'N. . . 

» 

JSR 

*+$04EC 

60042620 

000008 

3B7C 

0014 

n 

o 

• 

. . 

. 1 MOVE.W 

#$0014,$FCC4(A5) 


OOOOOE 

266D 

0010 

1 &m.. 

V 

MOVEA.L 

$0010(A5),A3 


000012 

2653 


'SS' 


MOVEA.L 

(A3),A3 


000014 

0C5B 

0000 


f 

CMPI.W 

#$0000,(A3)+ 


000018 

6600 

0008 

f f... 

1 

BNE 

*+$000A 

60042152 

00001C 

3A1B 


i . i 


MOVE. W 

(A3)+,D5 


00001E 

6600 

0010 

f f. . . 

t 

BNE 

*+$0012 

60042160 


. ..and so on 

You could position the insertion point at the beginning of the code and use the following 
Replace command: 

Replace -c 00 /?«41»/ "3tdt" # replace everything up to the 

# instruction with 2 tabs 

However, the previous command works only because DumpObj happens to place the 
instruction at column 42. The following example, by defining some Shell variables, works 
regardless of the exact column layout: 

Set hex "[0-9A-F]«4,6»" # 4 to 6 characters in the set 0-9 and A-F 

Set space "[ 3t]+" # 1 or more spaces or tabs 

Set chars "33* ?+33 f n # 1 or more of any character between 3 

# single quotes 

Replace -c «> /{hex}: ({space} {hex})«1,3»{space} {chars} {space}/ "3t3t" 
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Finding a whole word 

The following example illustrates how you could find an exact match for a C identifier that 
you had previously defined in the variable {ident}: 

Set tokensep " [—ia-zA-Z_0-9] 

Set CaseSensitive 1 

The following Find command is not quite right, because it selects not only the matched 
identifier but also the token separator on each side of the identifier: 

Find /{tokensep}{ident}{tokensep}/ 

The following Find command selects only the matched identifier. It accomplishes this by 
adding 1 to the starting position of the selection (Aselectionll), and uses that as the 
starting point for a new selection that extends to the beginning of the next token 
separator: 

Find A/{tokensep}{ident}{tokensep}/!!:A/{tokensep}/ 


# a token separator is any character 

# not in the set a-z, A-Z, or 0-9 

# set to "true"—the case of each 

# character must match 
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♦ Bulldozer 


If you are making a very large number of changes (such as scripted global 
replacements in a large file), that file's memory may become fragmented. If this 
happens, the rarely seen bulldozer Icon may replace your cursor. The bulldozer 
tells you that MPW is trying to clear more memory space for your file. 

If you regain the regular cursor, you can close (save) the window and reopen 
it, thus completely reinitializing its memory area. If the bulldozer lingers it may 
mean that your computer will be busy with this one script over the weekend. 
To avoid this problem. It is better to reboot and modify your script to proceed in 
stages so that you don't run out of file memory. 

For example, let's suppose that you have a 10,000-line file that you wish to edit 
with this script: 

clear -c /• / 

replace -c «> /"("/ "[" 

These two formatting commands operate on each of the 10,000 lines in the file, 
a total of 20,000 operations (assuming that each line was changed). Unless 
you have a gigantic amount of RAM, this is probably more work than your 
computer can comfortably handle. (Of course, you might also try to free more 
memory by turning off MultiFinder or increasing MPW's application area, but 
doing so would help only a little in this case.) 

If your Macintosh has 5 MB of RAM, then you might be able to perform the first 
10X100 operations of the first command without ever glimpsing the dread 
bulldozer. In this case, modify the script so that after the first command the 
script closes the window (thus automatically saving the file) and reopens it to 
continue with the next large operation: 

clear -c /• / 

close -y { MyEditWindow } 
open -t { MyEditWindow } 
replace -c ~ /"("/ "[" 

Alas, what If the bulldozer appears during the execution of the first command? 
First deduce at what point the bulldozer appeared (let's say somewhere well 
after the first 4000 lines were changed) and then modify your script to stop 
processing at regular intervals. In the example that follows, the editing 
operation stops after 4000 operations, closes the window (thus saving it 
automatically), and reopens it. Then the program returns to the top of the file 
and resumes editing for another 4000 operations. 

find* 

loop 

clear -c 4000 /• / 

break if {status}* 0 
close -y {MyEditWindoids 
open -t [MyEditWindouii 

end ♦ 
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Chapter 7 


Projector: Project Management 


Projector is a built-in MPW facility for managing Programming projects of 
any size. Projector makes it easy to keep track of the revision history of the files 
comprising your programs: who changed what, when, why, and other information. 
You can use Projector to create experimental branches of a project and later 
remerge the successful efforts. 

The syntax of all Projector commands is summarized at the end of this chapter. 
You can find detailed information and examples for each of these commands in 
Part II. There are a number of Projector-specific terms defined throughout this 
chapter; these terms can also be found in die glossary. ■ 
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About Projector 


Projector is a collection of built-in MPW commands and windows that help programmers 
(both individuals and teams) control and account for changes to all the files 
(documentation, source, applications, and so on) associated with a software 
development project. Use Projector to coordinate changes among a team of 
programmers and to maintain a history of project revisions. When you begin work on a 
project, you select the appropriate project and check out the files needed just as books 
are checked out from the public library—although in this case, Projector distributes both 
read-only and modifiable copies of its “books.” 

Projector requires the presence of MPW 3.0 and does not run outside MPW as either a 
Macintosh application or desk accessory. The terms and concepts introduced in this 
section are discussed in greater detail the the section “Components of a Project,” near the 
end of this chapter. 


Overview 

During the evolution of a software development project, each team member invariably 
makes numerous changes to the source and documentation files. Sometimes the changed 
source files are alternative versions or experimental efforts; later you want to discard the 
failed efforts and merge the best versions together. Projector is designed to substantially 
ease this task by providing an easy-to-use yet powerful facility for file management that is 
valuable to both the individual programmer working on a small project and to a tea m of 
programmers working on a complex set of programming projects. Use Projector to 
organize your files into projects that can be stored locally on a hard disk, a 3.5-inch disk, 
or remotely anywhere on the AppleTalk network. 

A project is a conceptual entity for organizing files, analogous to an HFS directory. Once 
within Projector, each file becomes a revision tree. Each revision tree comprises the 
entire historical sequence of revisions and branches of a particular file. Any of these 
revisions may be opened for reading only or checked out exclusively by one user for 
modification. Figure 7-1 shows how three files might appear as three revision trees in a 
hypothetical project The sequentially numbered circles represent revisions. Those circles 
with letter suffixes are branches, which may in turn sprout their own branches and 
subsequent revisions. The numbering scheme for revisions, branches, and revisions of 
branches is explained in the section “Revisions” later in this chapter. 
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■ Figure 7-1 A project structure 



When you check out a “file” for modification you are actually checking out a copy of a 
revision—usually the latest revision—from the file’s revision tree. The revision you have 
checked out appears in your HFS directory as an ordinary file named after its associated 
Projector revision tree. When you check it back in, the “file” becomes the next revision in 
its Projector revision tree. 

When checking out a file for modification you can write a comment describing the 
changes you’re about to make (so other project users can see why you have checked out 
the revision). Projector remembers that the revision is checked out and denies access to 
anyone else attempting to modify checked out revisions. (Of course, you can always 
create a new branch off a checked-out revision.) 

You can check the revision back into Projector at any time, although you would normally 
check in revisions as soon as your modifications are complete and tested. Once your 
revision is checked back in, the next sequential number is, by default, appended to its 
name to identify its place in the revision tree. This revision is now available to anyone on 
the team. 
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Besides supporting a single sequence of revisions to each file, Projector also allows 
alternative revisions to be created. This feature is called revision branching. Branching 
makes possible 

■ the modification of old revisions 

■ work on the same revision of a file by several programmers simultaneously 

■ parallel, experimental lines of development 

See the section “Creating Branches” later in this chapter. 

Whenever you go through the simple check-in process, you are encouraged to document 
all the changes you have made and the reasons for these changes. This allows the project’s 
current status and history to be easily retrieved by all team members. It’s also extremely 
handy when you have to go back through old revisions to find a problem or retrieve 
something of value. 

Projects may contain other projects, ailed subprojects. This last fact is of key 
importance, because it lets you break down large projects into subunits that an still be 
accessed as a whole by those outside the immediate programming team. See “Nested 
Projects” later in this chapter. 


Features 

Some of Projector’s key apabilities are listed here: 

■ Projects and subprojects can be organized into a hierarchy. 

■ All revisions to a file are saved in the revision tree. Each revision is uniquely iHpnrifWl 
by its filename and revision number. 

■ Nontext files as well as text files may be stored in the project 

A Important Be careful of programs that may inadvertandy delete Projector’s 

' ckid' (that is, check ID) resources from files. When a program such 
as Microsoft Word™ saves a file, it deletes the file’s • ckid’ resource. 
These resources contain the identifiation Projector uses to track 
files, a 
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■ Revisions made to text files are stored in a compact format. 

■ Access by multiple users is supported. Requests to modify the Project database are 
controlled by user name on a per-project basis. AppleShare can be used to assign 
privileges. 

■ A flexible naming facility allows revisions to be identified by symbolic name as well as 
by filename and revision number. (See “Symbolic Names” later in this chapter.) 

■ The entire history and status of all revision trees in the project can be displayed 
conveniently and accurately. A data field for comments is saved with revisions, 
revision trees, and projects. Projector also associates another data field, called Task, 
with every revision of a file. 

■ Projector supports a command line interface so that you can embed Projector 
commands in MPW Shell scripts. 

■ A window-based interface is provided for convenient and easy browsing and access to 
projects. Any or all Projector windows can be opened from the Project menu. 
(However, not all command-line functions are supported in the window interface.) 

■ Scripts that compare and merge revisions are supplied in " {mpw} Scripts:" 


Limitations 

Keep these rules in mind when using Projector: 

■ All files (revision trees) in a project must have unique names. 

■ There is no easy, integrated way to change a filename. 

■ Revisions cannot be arbitrarily deleted out of sequence. (See “Deleting Revisions” 
later in this chapter.) 

■ Revisions to nontext files are not compressed. 

■ Commas are not allowed in filenames. 

■ Symbolic names must not be hyphenated. 

See “Project Administration” later in this chapter for information on ways to get around 
some of these limitations. 
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Using Projector: A walk-through 


This section takes you through each step of the principle operations of Projector, 
demonstrating the functions of the principal windows. The concepts and organization will 
become evident as you go through this hands-on tutorial. 

First, you’ll create a new project. Next, you’ll check a new file into the project you just 
created. Finally, you’ll mount the project Sample and check out revisions from the project 
Utilities. 

The concepts used here are defined in detail in the section “Components of a Project” and 
the summary sections following this walk-through. You can also find Projector terms in the 
glossary. 


Creating a new project 

The simplest way to create a project is to use the New Project window. Follow these steps 
to create a project called Test: 

1. Double-click the MPW Shell icon to launch MPW and open the Worksheet 
♦ Note: Make sure that the {User} variable is set to your name. 

2. Type 

set user 'username' 

Note that the Chooser user name will be used if it is available. 

3. Set your directory to the Projector example folder by typing the following command 
in the worksheet: 

Directory "{MPW}Examples:Projector Examples:" 

4. Select New Project from the Project menu. The New Project window appears. You can 
display all of the other Projector windows in a similar fashion (see Figure 7-2). 
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■ Figure 7-2 New Project window 



5. Type the new projects name, Test, into the Project Name field of the New Project 
Window. 

6. You may add some descriptive information about the new project in the Comment 
field. 

7. Finally, click the New Project button at the lower right comer of the window. (If the 
user name is not specified, the New Project button remains disabled.) 

The New Project window should now look like the example shown in Figure 7-3, except 
that your name will appear in the User field. 
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■ Figure 7-3 New Project window after creating a project 



The left side of the New Project window is a list similar to that in the Standard File dialog; 
it displays the Macintosh’s HFS file structure. This lets you create a project anywhere in 
the file system, either under an existing project or in some other directory. 

You could also create the new project Test by using the command line 
NewProject Test 

This creates a project named Test whose project directory, created by Projector, is 
:Test. Projector maintains all information regarding this project in the file ProjectorDB 
within this directory. Nested projects will appear as folders within this directory. The 
checkout directory is set to the current directory at the time of the check out. (See the 
description of checkout directories later in this chapter.) 

Test is automatically mounted for you and also becomes the current project. Test can 
actually be an HFS pathname or, if a project is currently mounted, a Project pathname. In 
either case, the name of the new project is the leaf of the path. If an HFS path is given, 
that directory becomes the project directory for the new project. If a project pathname 
is given, the new project becomes a subproject of its parent, as shown here: 

NewProject Sample/Fortran 

This creates a new project, Fortran, which is a subproject of the Sample project. If the 
project directory of the Sample project were 

"{MPWJExamples:Projector Examples" : Sample: 

then the project directory of the Fortran project would be 

"{MPWJExamples:Projector Examples":Sample:Fortran 
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This command is equivalent to the previous example: 

NewProject "{MPW}Examples Projector Examples":Sample:Fortran 

Since the project directory of the Sample project is "(MPW}Examples:Projector 
Examples:Sample", the Fortran project automatically becomes a subproject of the Sample 
project. 

When you mount a project, all of its subprojects are mounted at the same time. See the 
section “Components of a Project” later in this chapter for more information on project 
directories and details of naming conventions. 


Checking in a revision 

When you have finished modifying an existing revision of a file, you should check it back 
into the project. When you want to add a new file to a project, follow the same 
procedure. 

You can add comments to indicate the changes you’ve made. Projector will record the 
date and time, as well as other information about the revision. The changes you have 
made become part of a new revision in the file’s revision tree. (Of course, read-only 
revisions cannot be checked in because they do not contain changes and therefore cannot 
create new revisions.) 

When using the Check In window keep in mind that the HFS directory (displayed in the 
list on the left side of the window) is similar to a regular Macintosh Standard File dialog 
that displays the files and folders. The Check In window’s list does not show files that are 
not a part of a project unless you click the Show All Files box. 

To check a new file into a project, follow these steps: 

1. Execute the following command to create a simple new file that can be used in this 
example: 

Echo "a new file" > newfile 

2. From the Project menu, select Check In. The Check In window appears (Figure 7-4). 

3. You must check the Show All Files check box at the bottom left of the window to 
select a new file because the list at the left side of the window, by default, lists only 
revisions that belong to the current project. 

4. Select the file “newfile” in the list at the left of the Check In window. 
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♦ Note: You can select several files at once for check-in. Use shift-click to select 
contiguous filenames by dragging. Use command-clicking to select discontiguous 
filenames. 

5. Type a comment into the comment field of the Check In window. Whenever you 
check a revision into a project, it is a good idea to add a comment describing the 
changes you’ve made (or in the case of a new file, its purpose). 

6. To check “newfile” in with an initial revision of “1.0” (the default would be “1”), click 
the Revision button. When the Revision Number dialog box appears, type “1.0” into 
the Revision field, and then click the OK button. The Check In window should now 
look like the example shown in Figure 7-4. 


■ Figure 74 Check In window 



7. Click the Check In button. 

Later, when you open the Check Out window, you will see that “newfile” has been entered 
into the project Test. 
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♦ Reading icons in the Check in window 


This is a list of small icons that may appear in the Check in window's list. 



Read-only. The file is a read-only file belonging to the current project. 

Modified read-only. The file is a modified read-only file (explained later in 
this chapter) belonging to the current project. 


The regular document icon represents a file that does not belong to any 
project. It is visible only when Show All Files is checked. 


J 


The pencil icon means that the HFS file is checked out from the current 
project for modification by the current user. 


® The lock Icon means that the HFS file is checked out from the current 
project for modification by another user. 

21 File belongs to a project other than current project. Appears only in the 
Check In window when Show All Files is checked. 

2l Modifiable file belonging to another project (denoted by the tiny plus 
sign in the lower-right comer). Appears only in the Check In window 
when Show All Files is checked. 


Corrupt * ckid’ resource (explained later in this chapter). Appears only 
In the Check In window when Show All Files is checked. ♦ 


Each of the features of the Check In window is discussed below: 

Project pop-up 

Click on the “Project:” field at the top center of the Check In window to select the current 
project This is the project into which you will be checking files. The HFS list (shown on 
the left side of the Check In window) will be updated to list the selected project’s 
associated checkout directory (if there is one). 
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User field 


The value of the {User} variable is displayed here. The {User} variable must be set in order to 
check in revisions. 

Info (question mark) button 

When you click the Info (question mark) button in the Check In window, the right side of 
the window displays Projector’s current information on the selected file (that is, the 
contents of the file’s ' ckid' resource). The Check Out window also has an Info View. 
Figure 7-7 shows the Info View of the Check Out window. If you are checking in a new file, 
the Info View is blank because Projector has not yet created a • ckid' resource for it. If 
you are checking in a revision that was checked out for modification, you can modify the 
Comment or Task fields in the Info View. These changes are saved in the revision’s 
'ckid' resource. 

Keep Read-Only, Keep Modifiable, and Delete Copy buttons 

The default action after checking in a file is to leave you with a read-only copy. The three 
radio buttons in Figure 7-4 can alter this default. The top button corresponds to the 
default; it leaves you with the read-only copy. Use the Keep Modifiable button to check 
in the file and still retain a modifiable copy. The Delete Copy button deletes your copy of 
the file once it is successfully checked in. These last two radio buttons correspond to 
the -m and -delete options of the Checkin command. 


Adding new files to a project 

You add new files to projects by checking the Show All Files check box in the Check In 
window (or by using the -new option of the Checkin command). When that check box is 
checked, all files in the current directory are shown. Any files not belonging to a project 
may then be selected and checked in. These files will be added to the current project 
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▲ Warning If, for any reason, the • ckid • resource of the revision is corrupted or 
removed, then Projector will not be able to identify the revision, 
which becomes an orphan file, no longer belonging to any project. If 
you still need to check the file in, move or rename your copy, cancel 
the check-out of the revision that is damaged (see “Checking Out a 
Revision” later in this chapter), check out the revision again, and use 
the TransferCkid command to move the Projector information from 
the checked-out revision to your orphaned file, a 


In the Check In window, you can select a file only if it is currently checked out. In other 
words, only the enabled filenames can be selected. This restriction means that only files 
that have been checked out for modification can be checked in. In the Info View, all files 
are selectable so that you can also get information on your read-only files. 

Touch Mod Date check box 

This check box appears on both the Check In and the Check Out windows. In both cases 
it lets you change the convention for time and date stamping. In the Check In window, 
Projector’s default is to leave the date and time of check-in untouched. Check the Touch 
Mod Date box to stamp the revision of the file that you are checking in with the current 
date and time, that is, the check-in time. 

(-.hang in g a revision’s revision number 

Use the Revision button in the middle right comer of the Check In window to open a 
dialog box that allows you to specify the revision number for the revision you are about to 
check in. Besides enabling you to specify the revision number, the Revision dialog box 
also lets you create a branch. This is useful when you want to save your changes but not 
along the main trunk of the revision tree. 

It is not possible to specify the name of the branch that will be created. 
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Locating a project 

The set of mounted projects defines a set of project trees. This list tells Projector the 
names of the mounted projects and where their project directories are located. If a 
project is not in one of those trees, the project cannot be accessed. If a root project is 
moved or renamed (by changing its project directory), users must change their 
MountProject commands in order to reconnect to the project 

Use the MountProject command to see a list of currently mounted projects. 


Checking out a revision 

The simplest way to check out a revision is to open the Check Out window (shown in 
Figure 7-5) by selecting Check Out from the Project menu. You can also use the Checkout 
command, as explained later in this section. 

Normally, when you begin work in MPW you first check out a revision for modification 
from a Projector revision tree. The checked-out revision then appears in your directory as 
a regular HFS file bearing the filename of its Projector revision tree. When you check this 
file back into its project, it will be saved as the next sequential revision in its revision tree. 

♦ Note: The Check Out facility in Projector does not copy the actual data if you already 
have a copy of the revision that you are checking out For example, if you already 
have a read-only copy of revision 5 of file.c in hd:work: and you check out a 
modifiable copy of revision 5 of file.c into that same directory, Projector does not 
recopy the data of that revision. The ' ckid' resource is updated to reflect the new 
check-out. 


Keep in mind that, unlike the Check In window, the list at the left side of the Check Out 
window lists the project heirarchy, not HFS. 

A checked-out revision matches its corresponding checked-in revision in all ways except 
for the * ckid • resource and optionally the modification date. By default, when 
checking out a revision, the modification date is set to the current time in order to trigger 
any makefile dependencies. This setting is needed to automatically trigger rebuilds when 
old revisions of source files are checked out You can override this default behavior by 
clicking the Touch Mod Date check box in the Check Out window or by using 
the -noTouch option to the Checkout command. 
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As part of the check-out process, you can leave a comment describing the changes you 
plan to make. Other members of your group can then see what is being done to the 
checked-out revisions. This does not prevent anyone else from reading the revisions in any 
revision tree of a project, but it does prevent anyone else from modifying the same 
revisions at the same time. After completing your work, check your revision back in with 
Projector, and add a note describing any changes you have made (if you had not done so 
when you checked out the revision or if you want to modify your initial comment). 

Follow these steps to mount the Sample Project: 

1. Click on the worksheet to make it the active window. 

2. Mount the sample project by typing this command: 

MountProject "{MPW}Examples:Projector Examples:Sample” 

3. Set the checkout directories by executing these commands: 

CheckOutDir -project Samplejcommands "{MPW}Scripts:" 
CheckOutDir -project Sample/utilities "{MPW}Scripts:" 

This directs Projector to place files from these projects into the Scripts folder. 

4. From the Project menu, select Check Out 

5. Find the Utilities project in the Project list at the left side of the window, select it, and 
click the Open button. The Check Out window appears as shown in Figure 7-5. 

♦ Note: The control at the left of the Check Out window is the Project list and works 
somewhat like a Standard File dialog, except that it displays only mounted 
projects and the revision trees and revisions within those projects. It does not 
show HFS directories. 
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■ Figure 7-5 Check Out window 



6. Choose the Modifiable radio button. 

7. Click the Select All button in the lower-left comer. This selects the lat es t trunk 
revisions of all revision trees that are not checked out for modification in the Test 
project (you have the option of selecting only individual revisions from the project). 

8. Click the Check Out button in the lower-right comer. 

♦ Note: You can automatically open a TEXT revision as you check it out by holding 
down the Option key while you click the Check Out button. 


Now you are ready to open and modify the revisions you have just checked out from the 
Utilities project No one else can modify the specific revisions you have checked out until 
you check them back in by using the Check In window (or Checkin command). 

The procedure for checking out nontext revisions is the same as the procedure for 
checking out text revisions. 
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♦ Reacfing icons in the Check Out window 

These visual cues may appear in the Check Out window. 

S A project. A similar, but larger Icon is used in the Finder to represent the 
ProjectorDB file. 

1© A Projector revision tree. Appears only in the Check Out window. 

0 The regular document icon represents an individual revision currently 
available. It is visible when an individual revision tree is displayed. 

J When a project is displayed (so that all its revision trees are listed), the 
pencil icon means that the latest revision of the main trunk is checked 
out for modification by the current user. When an individual revision 
within a revision tree is displayed (a list of revisions), the pencil icon 
means that the particular revision is checked out for modification by the 
current user. 

® When a project is displayed (so that all its revision trees are listed), the 
lock icon means that the latest revision of the main trunk is checked out 
for modification by another user. When an individual revision within a 
revision tree Is displayed (a list of revisions), the lock icon means that 
the particular revision is checked out for revision by another user. ♦ 


Here is an explanation of each part of the Check Out window: 

Checkout directory 

The 'Check out to” field in the window’s upper-right comer shows the directory where 
checked-out revisions will be placed. Clicking the field displays a pop-up menu that gives 
you three choices: 

■ The checkout directory for the current project 

■ The current directory 

■ Access to a Standard File dialog where you can choose any directory 

The directory that is displayed by default in the field is the check out directory for the 
current project (see CheckOutDir command). 
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User field 


The value of the {User} variable is displayed here. The {User} variable must be set in order to 
check out revisions. 

Task and Comment fields 

The Task and Comment fields are optional but it’s recommended that you get in the habit 
of always stating your purpose. Use the Task field to let others know why you have 
checked out the revision. This information can help later if you have to review a long 
revision history to find something. 

The Comment field is intended to document the specific changes to a revision while the 
Task field could be used to relate different revisions, perhaps across several files (that is, 
Projector revision trees). You can change the purpose stated in the Task and Comment 
fields when you check the revision back in. 

For example, implementing a certain feature might require several changes to each of three 
files. Each revision might have a different comment, but the tasks for all the revisions 
might say “Enhancement X.” The Task field makes it easier to look at the history of a 
project and determine what changes were made to accomplish various tasks. 

To save a Task field across several revisions, select the revisions in the list at the left of the 
window and type directly into the Task field of the Check In window proper. Then click 
the Check In button to check in the selected files. To save a unique Comment field with a 
particular revision, first select that revision and then click the Info button. Type into the 
Info view’s Comment field, click Save, and then click Done. 

Select Newer button 

Use the Select Newer button to select all the revisions for which the latest revision on the 
main trunk is not in the “Check out to" directory. Projector looks in the checkout 
directory to determine which revisions to compare against the project If you have a 
modifiable file (or a file that is on a branch) in the checkout directory, then the 
corresponding revision trees are not selected. In the case of modifiable files, this is done 
to prevent checking out a file by overwriting a modifiable file. In the case of any files 
that you may have on a branch, Projector assumes that you want to leave that file alone 

♦ Note: If you do have read-only copies of branches, then use the Select All button to 
ensure that you get the latest revision on the main trunk of every revision tree. 
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If you hold down the Option key as you use the Select Newer button, then revisions that 
are new to the project (that is, you don’t already have a copy of them) will not be 
selected. 

The Select Newer button cannot be used when checking out revisions for modification. 


Select All button 

If you are checking revisions out for modification, the Select All button will select all 
revision trees whose most recent revisions are not already checked out for modification. 
When checking out read-only copies, the Select All button will select all revisions in the 
project. 

♦ Note: The two buttons Select All and Select Newer do not actually check out revisions; 
they simply make a selection in the Project list (the leftmost frame of the Check Out 
window). Only the Check Out button (the button in the lower-right comer of 
Figure 7-5) actually checks out the selected revisions. 


Read-Only/Modifiable buttons 

The two radio buttons at the bottom of the window specify read-only or write-modify 
types of revision check out. The default is to check out read-only copies. Everyone with 
access to the project can check out revisions for reading-only at any time. But if the 
revision is checked out for modification, no one else can check that revision out for 
modification. 
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♦ Modifiable read-only file 

On rare occasions you may want to modify a read-only file. For example, 
suppose you have taken a number of modifiable files home. You may have also 
brought along certain read-only copies of files that you did not expect to 
modify. However, once you get into your work at home you discover that you 
do, after all, need to make changes in these files In such an exceptional ca se , 
you can use Projector's ModifyReadOnly command. In the Worksheet type: 

ModifyReadOnly filename 

You can now make changes to this read-only file exactly as if you had 
checked it out as a modifiable file, with two exceptions: 

■ Once it is saved, the special modifiable read-only icon appears next to the 
filename in the Project list. 

■ When you check a modified read-only file back into its project you will 
have no problem unless someone else has modified the same revision. In this 
case you must manually merge the two versions. See 'Merging Branches' 
later in this chapter for step-by-step instructions. 

Obviously, the ModifyReadOnly command is intended only as an emergency 
convenience; you should not routinely rely on it. ♦ 


Branch check box 

Use this check box to create a branch. This control is enabled only when doing modifiable 
check-outs. If the file that you have selected is locked, then this check box will be 
selected automatically. See the “Creating Branches” section that follows this walk-through 
for instructions on creating and merging branches. See the “Components of a Project” 
section for detailed explanations of branching in Projector. 


♦ Note: You can select dimmed files by holding down the Option key while you 
click the names. 


Touch Mod Date check box 

When the Touch Mod Date check box is checked, the revisions checked out (into the 
check out to directory) are touched, that is, the modification date is set to the date and 
time of check-out. If the box isn’t checked, the checked-out revisions have the samp 
modification date as when the corresponding revision was checked in. 
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Checking out a particular revision 

To check out a particular revision of a revision tree, first display the revision tree by 
selecting its filename and clicking the Open button (or you can simply double-click the 
filename). You can then select the revision you want You can select several noncontiguous 
filenames by command-clicking. 


Info (question mark) button 

If you have selected an individual revision in the Project list, clicking the Info button 
overlays the ri ght side of the Check Out window with the Info View, which is a display of 
the information pertinent to the selected revision. At this point you can edit the 
Comment and Task fields. You can also get information about revisions that are checked 
out for modification or information about any other revision in the project. 

Select Files in Name 

Click on the Select Files in Name field to display a pop-up menu showing both private and 
public symbolic names, the private names appearing at the top, the public at the bottom. 
When you select a symbolic name, the project list at the left side of the window highlights 
all revision trees that correspond to the selected symbolic name. Click the Check Out 
button to check out all of them. This makes it easy to select at any time just those 
revisions that comprise, for example, an alpha release. 

♦ Note: If you manually change the selection after selecting a symbolic name, you will 
void the selection of the name. 


Discarding changes 

To throw away any changes, use the Cancel Checkout button located in the lower-right 
comer of the window just above the Check Out button. For example, if half the revision 
trees were accidentally checked out for modification, you could undo the mistake by 
simply canceling their check outs. This button is also handy if you want to experiment or 
if you checked out a modifiable copy when you intended to make it read-only. 
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Using the Checkout command 

Revisions can also be checked out using the Checkout command: 

Checkout file.c -m 

This will place a modifiable copy of file.c in the checkout directory of the current proje ct . 
You can change the checkout directory by using the CheckOutDir command. If no project 
has been mounted, or if file.c does not exist in the current project, Projector reports an 
error. You can get a modifiable copy by using the -m option; the default behavior of 
Checkout is to distribute read-only copies. 

There are several different ways to specify where checked-out revisions should be placed. 
The roles for determining the directory are as follows, from highest to lowest precedence: 

1. The directory indicated if a nonleaf name is specified. 

2. The directory specified with the -d option. 

3. The checkout directory for the project (see the CheckOutDir command). 

For example: 

Checkout -d hd:MPW: file.c hd:work:defines.h 
Checkout hd:MPW:main.c library.h 

This first Checkout will place a copy of file.c in hd:MPW:file.c and a copy of defines.h in 
hd:work:defines.h. In this case, the checkout directory was not used. The second 
Checkout will place a copy of main.c in hd:MPW:main.c and a copy of library.h in the 
checkout directory for the project. 


♦ A quick switch from Read-Only to Modifiable 

You can quickly check out the active (frontmost) window and change its 
status from read-only to modifiable by using the CheckOutActive script found 
in the project 

{MPW}Examples:Projector Examples:Sample:Utilities: 

Likewise, you can quickly check in modifiable files by using the 
ChecklnActive script. ♦ 
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Creating branches 


In addition to supporting a sequence of revisions to a file in a project, Projector also lets 
you create branches. Branches are alternative sequences of revisions that are parallel to 
the main revision sequence. Branches may be used for 

■ the modification of old revisions 

■ work on the same revision of a file by several programmers simultaneously 

■ parallel, experimental lines of development 

You can create a branch off a revision during the check-out or check-in process by 
clicking the Branch check box in the Check In or Check Out windows. 

Checking out a modifiable copy of an old revision creates a new branch (as shown in 
Figure 7-6). When file.c is checked back in, it will automatically become Revision 2al. 


■ Figure 7-6 A changing revision tree 




The following command will create a branch when checking in a revision: 
Checkin file.c -b 
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In this example, the user did not need to specify a revision number to create a branch. 

The branch is automatically created off the revision that was checked out. This is possible 
because Projector remembers which revision was checked out When a revision (obtained 
from revision x) is checked back in, it can create a revision in one of two places: 

■ The next revision after x, continuing on the same line 

■ On a branch off revision x 

Referring to Figure 7-6, you’ll see that the user could not check in file.c as Revision 3al or 
Revision 5. 

The following command will create a branch and number the first revision 2: 

Checkin file.c,2 -b 

If Revision 4 of file.c was initially checked out, the preceding Checkin command would 
create Revision 4a2 (or 4b2 if Revision 4 already had one branch, and so on). 


Merging branches 

You can merge a branch revision with the trunk by using MergeBranch. You’ll find details 
on this script in Part II. 

1. Make sure you have checked out the branch revision you want to merge. 

2. Execute the MergeBranch script on the file you want to merge. 

MergeBranch file.c 
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Retrieving information 


Information retrieval is one of the most important aspects of any source file control 
system. Once again, there are two different ways to get information out of Projector: by 
using the Projectlnfo command or by clicking the Question button in the Check Out or 
Check In window. The information that you can retrieve from a project includes 

■ Project information 

□ Author 

□ Last modification date of the project 
a Project comment 

■ Revision tree (file) information 

□ Author 

d Date original file was added to the project 

□ Last modification date of the revision tree 
o Revision tree comment 

■ Revision information 

□ Author 

□ Task 

□ Date the revision was created 
o Revision comment 

The Check Out window’s Info View (see Figure 7-7) is designed to help you browse 
through the project, finding information about revision trees or individual revisions. The 
command-line interface can handle more complex batch-type requests, such as “list all 
revisions, including comments, that Bob made to a particular file, Commands.” 

The script CompareRevisions lets you compare two revisions side by side, highlighting the 
differences. Use of this script is described at the end of this section and in Part II. 
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Figure 7-7 Revision information 



You can also retrieve information in the Check Out window, by selecting a subset of the 
project to view via the View By dialog (see Figure 7-8). 


■ Figure 7-8 The View By filter 
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The View By dialog provides different items with which you can filter the revisions in the 
list Only revision trees or revisions that match your criteria will be displayed. To specify 
a filter, bring up the View By dialog box and select the items that are important to you. 
You may specify these items: 

■ The author of a revision tree or revision. All the authors known to the project will be 
listed in a pop-up menu. Select the desired author from the list 
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■ The file modification date or revision creation date. Type in the starting and ending 
dates. The format is dd/mm/yy [hh:mm[:ss] [AM I PM]]. To specify “on or since a date,” 
enter the starting date in the first box, and leave the second box empty. To specify 
“before or on a date,” enter the ending date in the second box, and leave the first box 
empty. 

■ File or revision comments. Type in either a literal string, or a regular expression in 
slashes (/regular expressionf). 

m Task comments. Type in either a literal string, or a regular expression in slashes (such 
as: /regular expression /). 

■ Name. The pop-up menu contains all your private names followed by the project’s 
public names. Select the desired name from the list You may also specify a relation to 
that n amt (for example, to list all the revisions since alpha). Select the desired relation 
from the pop-up menu next to the name. 

■ Modifiable. List only those revisions checked out for modification. 

■ Newer/Update. list only those revisions that would be checked out by using the 
corresponding option to the Checkout command. 

For the author, date, and comment items, you must specify whether each should be 

applied to revision trees or to revisions. 

♦ Note: The display of all the revision trees is affected unless you specify a “file” filter 
from the Revision/File pop-up menu. 


For example, in Figure 7-9, the user has specified a filter to list all revisions in alpha, 
created by John Dance, on or after August 12,1988, dealing with Bug #222. 


■ Figure 7-9 The “View By” dialog with selection criteria 
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The following Projectinfo command is equivalent to the View By dialog in Figure 7-9. 
Projectlnfo -a 'John Dance* -d *>8/12/88' -t */bug=222/' -n alpha 

Selecting a project displays information about the project (see Figure 7-7). Selecting a 
revision tree either displays the current state of the revision tree, that is, the status of the 
latest revision (see Figure 7-7), or it displays the revision tree information. Which is 
displayed depends on the radio buttons in the upper part of the window’s information 
display (see Figure 7-7). Double-click a filename to display its revision tree. The latest 
revision is selected by default, and its information (status) is displayed. Selecting another 
revision displays its status. The Comment and Task fields are editable so that changes or 
additions can be made to old comments. 


Comparing revisions 

You can compare two revisions by using the script CompareRevisions. You’ll find details 
on CompareRevisions in Part n. 

1. Make sure you have checked out the branch revision against which you want to 
compare another revision. 

2. Execute the CompareRevisions script on the file you have checked out 


Components of a project 

This section explains in detail how Projector works. Projector keeps track of these 
components for each project under its supervision: 

■ Projects 

■ Nested projects (subprojects) 

■ The files (revision trees) belonging to a project 

■ All revisions of each file (revision tree) 

■ The branches of each file (revision tree) 

■ Names of every user creating or modifying a file or project 

■ Symbolic names 

Each of these components is discussed in the sections that follow. 
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Projects 


A project consists of a project name, an author, some text describing the project, a set of 
revision trees belonging to the project, and whatever subprojects the project may have, 
which are actually projects in their own right. The author is the person who created the 
project. 

Projects can reside locally on an individual user’s disk, or they can be placed on an 
AppleTalk file server to facilitate access by multiple users. AppleShare can be used to 
assign access privileges to various users. (Projector does not itself provide facilities for 
assigning access privileges.) 

Use the Project command to set and show the current project. Projector assumes that all 
Projector commands pertain to the current project unless told otherwise. 

The project directory is the directory in which a given project resides. It is defined at the 
time the project is created. All revisions to all revision trees and all other Projector 
information are kept in the project directory within the project file, called ProjectorDB. 
All users access the same ProjectorDB. Nested projects are also kept in this directory as 
subdirectories. (See “Nested Projects” later in this chapter.) 

Every user has a checkout directory for each project. This is the directory into which, by 
default, Projector places checked-out revisions. You can change the checkout directory 
by using the CheckOutDir command. 

Each user can select one or more projects for access by using the MountProject command. 
Selecting a project makes it and all its nested projects (subprojects) accessible to the 
user. You can remove projects from the root project list with the UnMountProject 
command. The MountProject and CheckOutDir commands allow individuals to 
customize their own project name space. 

It is easy to check out one revision into more than one directory by changing the 
checkout directory with the CheckOutDir command or by explicitly specifying the 
directory with the -d option. This makes it easy to look at an old revision of a file or to 
compare the differences between revisions. 

▲ Warning This flexibility of the CheckOutDir command might inadvertently 
cause problems during check-out because the modifiable revision 
might not be in the usual checkout directory. ▲ 
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Typically, the UserStartup file, a script, or AddMenu contains a series of MountProject and 
CheckOutDir commands that connects users to a set of projects. Simply mounting a 
volume does not give you access to the projects that are contained on that volume. This 
would be undesirable since many projects may not be of interest to every user. 


■ Figure 7-10 Sample project check-out configuration 
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The location of the project directory is the same for everyone, but the checkout directory 
can be different for each individual. For example, Bob and Peter both access the 
Commands project, but they have different checkout directories (see Figure 7-10). When 
Peter checks out files, they go by default to Rambo:work:Commands. Bob’s files, on the 
other hand, go to hd:MPW:Sample ProjectCommands:. 

Peter’s UserStartup could contain the following commands: 

MountProject FileServer:Projects:Sample:Commands 
CheckOutDir -project Commands! Rambo:work:Commands 

Bob’s could contain 

MountProject FileServer:Projects:Sample: 

CheckOutDir -project Sample! "hd:MPW:Sample Project" 

CheckOutDir -project Samplejcommands "hd:MPW:Sample Project:Commands" 
CheckOutDir -project Samplejutilities hd:MPW:Utils 

(See the MountProject and CheckOutDir commands in Part II for more information and 
examples.) 

Projector provides two ways to specify the current project, that is, the project a 
mmmanH will affect. The order of precedence (from greatest to least) is 

1 . Use the project specified on the command line with the -project option. 

2. Use the current project specified by the Project command. If you set the current 
project to the name of a particular project, then you don’t need to specify that 
project with every succeeding use of a Projector command. The current project is thus 
analogous to the current directory of the Directory command. 

If Projector cannot determine the current project, an error is reported and the command 
is aborted. In the Check Out window you select the current project in the Project list, just 
as you would select a file in a Standard File dialog box. In the Check In window, click on 
the “Project:’’ in the upper-left comer to display the Project pop-up menu. 


Nested projects 

Projector supports nested projects, also called subprojects. A series of related projects, 
such as the example projects found in the Examples folder of MPW, can be configured as a 
hierarchy of projects. People can then access the project structure on any level they 
choose, mnrh in the same way people use HFS (see Figure 7-10). See Figure 7-11 for a 
sample project hierarchy. 
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■ Figure 7-11 A sample project hierarchy 


Sample/ 



In Figure 7-11 the Sample project is the highest level project, that is, it does not have a 
parent project. Projects are represented as circles, and revision trees (that is, files with all 
their associated revisions) are represented as smaller boxes. Just as you can mount several 
volumes, you can also mount several projects. However, Projector does not allow root 
projects to have identical names. In Figure 7-11, mounting the Sample project gives you 
access to all the projects in the project tree. 

Projects are named much in the same way as directories, except that the integral cbancter 
(J), obtained by pressing Option-B, is used as the name separator. Projector requires full 
Project pathnames at all times. Partial pathnames are not supported. Use of the integral 
character at the end of a project path is optional. 

■ To avoid confusion with HFS pathnames, Projector does not use colons as 
project pathname separators. Some commands, NewProject for instance, 
accept both HFS and project paths as parameters. Because the separators are 
different, there is no confusion as to what the parameter represents. 

■ Integral characters ( / ) are not allowed in Project names for the samp reason 
that colons are not allowed in HFS paths. 
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Revision trees 

When a file is added to a project, it forms the first revision of a new revision tree. The new 
revision tree bears the original file’s name. Each revision tree in a project consists of the 
following components: 

■ A name 

■ An author, the person who added the original file to the project 

■ A comment describing the revision tree 

■ A record describing the current state of the revision tree, that is, who has checked out 
the revision tree and all of its revisions 

■ The set of revisions and branches of the original file 

Projector can be used with all types of files, such as TEXT, OBJ, APPL, application 
documents, and so on. The only difference between text files and nontext files is that 
revisions to nontext files are not compressed, and they cannot be automatically opened 
at check-out time. Otherwise, there is no distinction between text and nontext files. You 
can check out read-only copies of nontext files, or check out any such revision for 
modification and then check it back in as a new revision. Revisions of nontext files can 
also be named and deleted. 

Each time a programmer checks in an updated copy of a revision, a new revision is 
created. As changes are made and the number of revisions grows, a revision tree forms. 
The revision tree traces the history of the file. By accessing various portions of this tree 
you can retrieve, inspect, and compare any of the previous revisions of a file. Projector 
also allows old revisions to be deleted when they are no longer of interest, provided that 
you delete all old revisions prior to a selected revision. In other words, arbitrary deletion is 
not allowed. 

Once a revision is checked out for modification, it is locked, thus preventing a second 
modifiable copy of that revision from being checked out at the same time. You may 
check out a read-only copy of the locked revision. 

However, it is possible to check out a modifiable copy of another revision. If you insist 
on rhprking out a revision that is already locked, Projector creates a branch for this new 
copy. You an later merge the changes to synchronize the file. Figure 7-12 shows a revision 
tree with branches and revisions of branches. 

Each revision in a revision tree contains the following identification: 

■ A revision number 

■ A creation date 

■ A Comment field describing the reason for the revision 

■ A Task field describing any specific tasks undertaken or any other information 

■ The author of the revision 

■ A copy of the revision itself (compacted in the case of TEXT files) 
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■ Figure 7-12 A revision tree 


Revision Tree 
file.c 



Revisions are normally identified in numeric order, that is, 1, 2,3,, 99,100,101, and so 
on. However, you can use major/minor numbering instead, that is, 1.1,1.2,1.3,... 1.99, 
1.100,1.101,... 2.1,2.2, and so on. When a new revision is checked in, Projector will 
automatically increase its revision number by 1, for example, from 4 to 5, or 4.9.2 to 4.9.3. 
You can override this action by specifying a different revision number. The only 
restriction is that this new number must be sequentially greater than the revision that was 
checked out Here’s the syntax for major/minor numbering. 

Revision Numbers: Major[. Minor..] 

To specify a particular revision in a command, append a comma followed by the desired 
revision number to the end of the name. In other words, file.c,3 refers to revision 3 of 
file.c. (Remember that commas are not allowed in project filenames.) The first command 
in the following example checks out the latest (current) revision of file.c. The second 
command checks out revision 3 of file.c regardless of what the current revision is 

Checkout file.c 
Checkout file.c,3 

The following command checks in file.c, forcing the revision to 4.1: 

Checkin file.c,4.1 

This command is legal only if the revision that was checked out was less than 4.1—for 
example, 4,3.9,4.0.9, or 2, and so on. 
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Branches 


In addition to supporting a sequence of revisions to a file in a project, Projector also lets 
you create branches. Branches are alternative sequences of revisions that are parallel to 
the main revision sequence. 

In Figure 7-3, Revisions 1, 2,3, and 4 form the main trunk of file.c’s revision tree. 
Revisions that are not on the main trunk form branches. These branches can be easily 
identified by the alphabetic character embedded in the revision number. For example, 
you might check out Revision 2 of a file and check it back in as Revision 2al, instead of 
Revision 3. This would begin the new sequence, 2al, 2a2, 2a3, and so on. A second branch 
off Revision 2 would create Revision 2bl. Revisions off branches follow the same default 
numbering scheme as revisions on the main trunk, 1,2,3, and so on. However, you can use 
major/minor numbering, with an arbitrary number of minor components. 

When specifying a revision, a name such as file.c,2a denotes the latest revision on the “a” 
branch of Revision 2. If there are two revisions, 2al and 2a2, then Revision 2a2 is used. 

To refer to particular revisions when using the Check Out window, double-click on a 
filename to display its revision tree. You can then select and act upon the individual 
revisions—to check out a particular revision of a file or get information about that 
revision. To interactively check in a file with a particular revision, click the Revision 
button in the Check In window. This displays a small dialog that lets you change the 
number. 


User names 

Most Projector commands require a user name to keep track of who did what. These 
commands report an error if no user is specified. Projector reserves the Shell variable 
{User} as a place to maintain the current user name. The MPW Shell initializes the {User} 
variable at launch time to the User Name field in the Chooser. When you use Projector 
interactively, via its windows, the current value of {User} appears in the User field. On the 
command line there are two ways to specify the current user. In their order of precedence 
(from greatest to least), they are 

1. Use the name given on the command line (via the -u option) 

2. Use the name given in the {User} variable. 

♦ Note: User privileges should be handled by AppleShare. Because AppleShare 

determines privileges when a network volume is initially mounted, changing the {User} 
variable will not change the access privileges to those corresponding to the new user. 
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Symbolic names 


Projector supports a general-purpose naming facility, NameRevisions, that allows project 
users to easily specify revision trees, versions, and branches within a project. Using 
NameRevisions you can create a name that symbolically represents a set of files almost 
anywhere Projector accepts a set of files. For instance, you could use a name to specify 
the “latest revisions oP a set of files that are checked out regularly. You could also use a 
symbolic name to specify the “alpha version” that labels a set of the revisions that can be 
used to build an alpha version. 

Names are specified by the project user. These restrictions apply: 

■ The first character of a symbolic name Name cannot be a digit (0-9). 

■ Commas are not allowed anywhere in a name. 

■ Greater-than or less-than symbols (<,<,>,>) are not allowed anywhere in a name. 

■ Dashes(-) are not allowed anywhere in a name. 

■ Names are not case sensitive. 

■ Names are kept on a per-project basis and can refer, at most, to one revision per 
revision tree in that project. 

For example, the following commands create the symbolic name Work for three revisions 
that you always check out together. Thereafter you need only check out Work. 

NameRevisions Work file.c file.h library.c 
Checkout Work 

Projector cannot create symbolic names by using the Set command and the existing Shell 
variable mechanism for these reasons: 

■ Names can refer to only one revision per file. Shell variables are arbitrary text macros, 
so this restriction could not be enforced. 

■ Names are kept on a per-project basis. In Projector the scope is the current project. 

In the Shell, scope is based on nested scripts. 

■ Names do not need special delimiters ({ and }) to be recognized, unlike Shell 
variables, which do require delimiters. 
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By default, names are expanded to the revision level when they are defined, not when they 
are used. Alternatively, by using the -dynamic option, the names will be expanded to the 
revision level when they are used, not when they are defined. In the above example, the 
name Work has expanded to the latest revisions of the three revision trees at the time 
Work was defined. This means that the revisions that Work implies will never change as 
new revisions to those revision trees are created. You can also explicitly bind a name to a 
revision (even while using the -dynamic option) by including the revision number at the 
time of definition. This example illustrates the differences: 

NameRevisions Work file.c file.h library.c 

is equivalent to 

NameRevisions Work file.c,6 file.h,3.5 library.c,7 

where the specified revisions are the latest revisions of the respective revision trees at the 
time Work was defined. The -dynamic option allows you to postpone expanding 
revisions to the revision level until the name is used. For example, 

NameRevisions -dynamic Work file.c,4 file.h,3 library.c 

may be equivalent to 

NameRevisions -dynamic Work file.c,4 file.h,3 library.c,5 

at one time, and equivalent to 

NameRevisions -dynamic Work file.c,4 file.h,3 library.c,21 

at a later point in time. 

Names are recursively expanded until no further expansion can occur or until a comma is 
found. For example, given the following names: 

NameRevisions defs.h defs.h,1.1 
NameRevisions file.c file.c,2.0 

NameRevisions -dynamic Work file.c defs.h,2.1 library.c 

this Checkout command, 

Checkout Work 
expands to 

Checkout file.c,2.0 defs.h,2.1 library.c 

Because an explicit revision was specified for defs.h in the definition of Work, the 
expansion of defs.h to defs.h,! .1 does not occur. 
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Names are particularly useful when working on a branch. For example, suppose you are 
designing a new algorithm in file.c and want to implement the algorithm on branch 4a of 
file.c. By defining this name: 

NameRevisions -dynamic file.c file.c,4a 

you can automatically check out and check in the latest revisions on the 4a branch. 

The command 
Checkout -m file.c 

checks out a modifiable copy of the latest revision on the 4a branch of file.c. You can 
override the name simply by specifying a particular revision along with the name. 

The command 
Checkout file.c,3 

checks out revision 3 of file.c, regardless of any names. Because an explicit revision was 
given, no name expansion occurs. A comma with no subsequent revision number denotes 
the latest revision on the main trunk of the revision tree. 

The command 
Checkout file.c, 

checks out the latest revision on the main trunk of file.c. If file.c has not been defined as 
a name, the comma at the end is unnecessary. 

Names can be defined recursively in a project tree. Going back to Figure 7-10 as an 
example, suppose Bob wanted to freeze the current state of his projects and name the 
current version Release 1. Then the command 

NameRevisions -a -r -project Sample "Release 1" 

would create the name Release 1 in each of the projects. This name would thus expand to 
the latest revisions when the name was defined. This command is equivalent to the 
following: 

NameRevisions -project Sample/ "Release 1" -a 
NameRevisions -project Samplejcommands "Release 1" -a 
NameRevisions -project Sample/utilities "Release 1" -a 

Both public and private (the default) names are supported. Public names are visible to all 
members of the project. Local names are visible only to the individual who created them. 
Local names can be declared in the UserStartup file by using the NameRevisions command. 
Public names are stored with the project itself. 
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Project administration 


The administrative duties for projects under Projector are very simple. Anyone who has 
write access to the project (under AppleShare) can administer the project. 
Responsibilities include 

■ moving, renaming, and deleting projects 

■ deleting old revisions that are no longer needed 

■ renaming a file in a project 

■ deleting files that do not belong in the project 


Moving, renaming, and deleting projects 

You can move or rename a project by using the Finder or the regular MPW commands. 

Simply renaming the project directory will rename the project. 

No other Finder or MPW operations are allowed on project directories. 

There ate two points to keep in mind when moving or renaming a project 

■ When you move or rename a project, the project hierarchy changes; 

MountProject commands must be modified to reflect the location of the 
project. 

■ It is highly recommended that projects be moved or renamed only when no 
revisions are checked out for modification, and that after the project has 
been changed all read-only copies be checked out again. This is 
recommended because Projector puts the project name in the resource forks 
of revisions during check-out Once the project is moved or renamed, the 
information is no longer valid. 

You can delete an entire project by deleting the folder containing the project. Use the 

Finder or the MPW Shell’s Delete command. 

▲ Warning Once you delete the project, all files and their revisions are lost, a 


234 MPW 3-0 Reference 






Deleting revisions 

You can delete old revisions in a revision tree by using the DeleteRevisions command and 
specifying the oldest revision that you want to keep. All prior revisions are then deleted. 

For example, if you specify the revision filename, 5, then filenames revisions 4,3, 2, and 1 
are deleted, leaving filename,5 intact. You cannot, however, arbitrarily delete filename, A 
while leaving revisions 3, 2, and 1 intact This restriction prevents confusion of the 
revision numbering scheme. 

You can delete entire branches by naming the branch (for instance, filename.c,22a). 

▲ Warning Once you delete revisions, there is no way to recover them. ▲ 


If you accidentally check a file into the wrong project, you can remove it and all its 
revisions by using the -file option of the DeleteRevisions command. 


Renaming a file In a project 

It is impossible to rename a file in a project Instead, you must check out the file you 
wish to rename and check the file back in under a different name by first using the 
OrphanFiles command. 


File organization within a project directory 

A project resides in an HFS directory called the project directory. The name of this 
directory is the name of the project. You need not worry about the exact file structure 
within a project directory. 

All information regarding a project, including all revision trees, revisions, comments, and 
so on, is kept in a single HFS file called ProjectorDB with the type 'mpsp •. 
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CHID resource 


Projector maintains a ' ckid' (Check ID) resource in the resource fork of all files that 
belong to a project This is where Projector identifies each revision tree’s filename, 
project, user, revision number, and so on. The structure of this resource is subject to 
change by Apple. 


Projector icons 

As you browse through the project hierarchy in Projector windows, look for the following 
visual cues that convey revision ownership. 

Icons Appearing in the Check In Window 

Read-only. The file is a read-only file belonging to the current project. 

Modified read-only. The file is a modified read-only file belonging to the current 
project. 

0 The regular document icon represents a file that does not belong to any project It 
is visible only when Show All Files is checked. 

The pencil icon means that the HFS file is checked out from the current project for 
modification by the current user. 

A The lock icon means that the HFS file is checked out from the current project for 
modification by another user. 

@ File belongs to a project other than current project. It appears only in the Check In 
window when Show All Files is checked. 

21 Modifiable file belonging to another project (denoted by the tiny plus sign in the 
lower-right comer). Appears only in the Check In window when Show All Files is 
checked. 

IS Corrupt • ckid ' resource. Appears only in the Check In window when Show All Files 
is checked. 
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Icons Appearing in the Check Out Window 

S A project. A similar, but larger icon is used in the Finder to represent the 
ProjectorDB file. 

© A Projector revision tree. Appears only in Check Out window. 

Q The regular document icon represents an individual revision currently available. It is 
visible when an individual revision tree is displayed. 

.P When a project is displayed (so that all its revision trees are listed), the pencil icon 
means that the latest revision of the main trunk is checked out for modification by 
the current user. When an individual revision tree within a project is displayed (a list 
of revisions), the pencil icon means that the particular revision is checked out for 
modification by the current user. 

® When a project is displayed (so that all its revision trees are listed), the lock icon 
means that the latest revision of the main trunk is checked out for modification by 
another user. When an individual revision tree within a project is displayed (a list of 
revisions), the lock icon means that the particular revision is checked out for 
revision by another user. 
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Projector command summary 

The syntax of the commands used to operate Projector are summarized here for your 
convenience. Detailed information on each of these commands can be found in Part II. 


Checkin -w 1 -close 1 

[-u user] [-project project] [-t task] [-cs comment 1 -cf file] [-p] 

[-new 1 -b][-m 1 -delete] [-touch] [-y 1 -n 1 -c] (-a 1 file...) 

Checkout -w 1 -close 1 

[-u user] [-project project [-m 1 -b [-t task]] [-cs comment 1 -cf fild [-p] 

[-d director# [-r] [-open] [-y 1 -n 1 -c] [-noTouch] [-cancel] 

(-update 1 -newer 1 -a 1 file...) 

CheckOutDir 

[-project project [-m] [-r] [-x 1 director# 

DeleteNames 

[-u user] [-project project] [-public] [-r] [names... 1 -a] 


DeleteRevisions [-u user} [-project project [-file] [-y] revision... 

ModifyReadOnly filename 

MountProject [-s] [-pp] [-q] [-r] [projecii 

NameRevisions [-u User] [-project Project] [-public I -b] [-r] 

[[-only] I name [[-expand] [-s] [-replace] I [(names... [-dynamicD I [-a]]]] 

NewProject-w I -close I 



[-u used [-cs comment 1 -cf fild project 

OrphanFiles file... 


Project 

[-q 1 projectName] 

Projectlnfo 

[-project projecii [-log] [-comments] [-latest] [-f] [-r] [-s] [-only] [-m] [-af author] 

[-a author] [-df dates] l-d dates] [-cf pattern] [-c pattern] [-t pattern] [-n name] 


[object...] 

TransferCkid sourceFile destinationFile 
UnmountProject [-a I project] 
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Chapter 8 The Build Process 


This chapter describes the mechanics of building a program. The steps 
involved are nearly the same for applications, desk accessories, stand-alone code 
resources, drivers, and MPW tools. (However, you’ll find special instructions on 
building your own MPW tools in Chapter 12.) All programmers should read the 
opening sections of this chapter, which explain the entire build process for an 
application, the usual case. Later sections explain what’s different about building 
a desk accessory, stand-alone code resource, or driver. 

Those new to MPW should first read “Building a Program: An Introduction” in 
Chapter 2. This brief introduction takes you through the steps of using the 
Directory and Build menus to build a simple program. For more detailed 
information on using the linker and how it works, see Chapter 10, “More About 
Linking.” ■ 
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Overview: the build process 


Building a program consists of the following steps: 

1. Create source files and compile them. Source files are compiled or assembled to 
produce object files. For information on writing programs in MPW Pascal, MPW C, or 
MPW assembly language, and including the proper interface or include files, see the 
appropriate language manual. Chapter 12 describes writing an MPW tool. 

2. Create noncode resources with ResEdit or Rez. If your program requires any additional 
resources (other than code resources), you can create them by using the resource 
editor (ResEdit) or resource compiler (Rez). These may be decompiled with DeRez 
into text files that can be further modified by the Shell editor before being 
recompiled with Rez (see Figure 8-1). See Chapter 11 for detailed information. 

3. Create the final executable file with Link. The object files are linked together, along 
with any needed library routines, into either a new resource file or an prating one 
(replacing the * code », • drvr •, or other executable resources). The output of link 
should be placed in the same file as any resources created in Step 2 (except in the case 
of drivers, as noted in the next paragraph). 


♦ Note: To build a desk accessory or driver in Pascal or C, an additional step is required: 
you must run Rez to create the final • drvr' resource. For details, see 'Building a Desk 
Accessory or Driver,” later in this chapter. 


Figure 8-1 illustrates the complete process. 
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Figure 8-1 The Build process 
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In Figure 8-1 you’ll notice that the output from the linker may be placed in a file with the 
“.code” extension. That file is then reprocessed with Rez to build the final application 
program. Also keep in mind that it is usually best to run Rez before running Link, even 
though Rez appears to the right in Figure 8-1. If you do mn Rez after running Link, 
remember to use the -append option. 

For example, the following series of commands compile, run Rez to compile the resource 
file, and link the sample Pascal application Sample.p: 

Pascal Sample.p 

Rez Sample.r -o Sample 
Link Sample.p.o 3 

"{Libraries}"Interface.o 3 
"{Libraries}"Runtime.o 3 
"{PLibraries}"Paslib.o 3 
-o Sample 

This process is usually automated by using the Make tool. (See the sample makefiles in the 
Examples folders, and “Using Make” in Chapter 9.) 

♦ Note: If you build an application with customized icons for documents (that is, a 
* bndl' resource for bundling 'icn#' and 'fref' resources), then you need to use 
setFile to set your application’s bundle bit like this: 

SetFile -a B MyApp 


See the chapter “Finder Interface” of Inside Macintosh for information. 
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The structure of a Macintosh application 


Macintosh files have two forks: a resource fork and a data fork. The resource fork 
contains a number of resources. The data fork may contain anything the application puts 
there. On the Macintosh, a program is a file whose resource fork contains code resources 
('code’ or other executable resources), and in most cases additional resources 
containing strings, dialogs, menus, and the like. The code resources for applications and 
tools must contain a main program (an execution starting point). Desk accessories and 
drivers, by contrast, don’t require a main program, but instead contain collections of 
routines that are called individually when the desk accessory or driver is used. 

The simplest possible application has two resources in the resource fork and nothing in 
the data fork. The first resource is a ' code * resource with ID = 0. (The linker creates this 
resource, which contains the jump table and information about the application’s use of 
parameter and global space.) The second resource is a ' code ' resource with ID = 1, which 
contains the application’s code segment For more information, see the chapter “Segment 
Loader” of Inside Macintosh. 


Linking 

This section describes how to link an application, desk accessory, or driver. (The process 
is very similar in the case of MPW tools. Special information on linking MPW tools can be 
found in Chapter 12.) 

For more detailed information about linker functions, see Chapter 10. The Link command 
itself is described in Part n. The MPW object-file format is described in Appendix H. 

Use the command Link to link object files into an application, desk accessory, driver, or 
other executable resource. By default, linked segments are placed in • code • resources in 
the resource fork of the output file. Link links together the compiled or assembled object 
files, along with any needed library routines, into either an existing resource file (replacing 
the ' code ', » drvr* , or other executable resources of the type that it is creating) or a 
new one (Figure 8-2). 
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Figure 8-2 Linking 



The linker resolves all symbolic references and controls final program segmentation. A 
related tool, Lib, provides facilities for modifying and combining object files (libraries). 

Link’s default action is to link an application (type APPL, creator"????"), placing the 
output segments into * code ’ resources. You can set a file’s type and creator with 
Link’s -t and -c options. (See “File Types and Creators” later in this chapter.) 


What to link with 

Applications, MPW tools, and desk accessories should be linked with the libraries listed in 
Table 8-1. Its wise to link new programs with all of the libraries that might be needed. If 
unnecessary files are specified, Link displays warnings indicating that they can be 
removed from your build instructions. 
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■ Table 8-1 Files to link 


Files 

Description 

Inside Macintosh interfaces 

{Librariesllnterface .o 


Runtime support 

Link with one of the following: 
{LibrarieslRuntime .o 
{CLibrarieslCRuntime.o 

If no part of the program is written in C 

If any part of the program is written in C 

Pascal libraries 

{PLibrarieslPasLib.o 

(PLibrarieslSANELib.o 

Pascal language library 

SANE numerics library 

C libraries 

{CLibrarieslCInterface.o 

{CLibrariesjCSANELib.o 

{CLibrariesjMath.o 

(CLibrarieslStdCLib.o 

Macintosh interface for C 

SANE numerics library 

Math functions 

Standard C library 

Specialized libraries 

{LibrarieslObjLib.o 
{LibrarieslToolLibs .0 

Object-oriented programming (Pascal and Assembler) 

Routines for MPW tools 

Desk accessories 
{LibrarieslDRVRRuntime.o 

Driver runtime library 

For derails about linking stand-alone code resources or desk accessories refer to “Building 
a Stand-Alone Code Resource,” or “Building a Desk Accessory or Driver,” later in this 
chapter. Details on linking an MPW tool can be found in Chapter 12. MPW tools libraries 
(the Cursor Control and Error Message File manager routines) are listed in Appendix F. The 
library of 3-D graphics routines is in Appendix G. 


Linking multilingual programs 


When you link programs that use libraries from more than one language, the linker may 
detea several duplicate entry points. Normally it doesn’t matter which of the duplicate 
copies of a particular routine are linked with your program. (You can use link’s -d option 
to suppress the duplicate definitions warnings.) 
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However, programs written partly in C and partly in assembly language or Pascal require 
special precautions. When you link C code with other languages, link with the file 
CRuntime.o and not with Runtime.o. If execution is expected to begin with the C 
function main (), no special action is necessary. However, if your main program is 
written in assembly language or Pascal, but part of your program is written in C, then you 
must do one of two things: 

1. Place the object file containing your main program before CRuntime.o in the list of 
object files passed to Link. 

2. Use link’s -m option to specify the name of the main routine. 

For more hints on using Link’s -m option, see “Dead Code” later in this chapter. 


File types and creators 

When you execute a command, the Shell determines how to run it based on its file type. 
Files of type APPL are considered applications and are run as if launched from the Finder. 
Files of type MPST are considered MPW tools and are run within the Shell environment 
Files of type TEXT are taken to be scripts and are interpreted by the Shell. An attempt to 
run a file of any other type produces an error message. Table 8-2 summarizes file types and 
creators. 


■ Table 8-2 File types and creators 


Type of program 

Type 

Creator 

Application 

APPL 

any 

MPW tool 

MPST 

'MPS' 

Desk accessory 

DFIL 

DMOV 

Script 

TEXT 

any 


See Table E-l in Appendix E for a complete list of special MPW file types. 

♦ Note: Each application has its own unique creator (or signature). For more 
information see the chapter “Finder Interface” of Inside Macintosh. For example, 
creating a file with the type DFIL and creator DMOV tells the Font/DA Mover that this 
file contains desk accessories. 

You can set a file’s type and creator with the -t and -c options to Link, Rez, or SetFile. 
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Building a stand-alone code resource 

When developing programs for the Macintosh environment, it is often desirable to build 
stand-alone code resources. For example, you may want to create custom controls. Some 
of these resources are 

WDEF window definition procedure (for custom windows) 

CDEF control definition procedure (for custom controls) 

LDEF list definition procedure (for List Manager) 

MDEF menu definition procedure (for custom menus) 

INIT a code resource that is loaded and run at boot time by the system startup code 

XCMD external command for HyperCard 

These rules must be observed to create a stand-alone code resource: 

1. No global or static variables can be declared. No calls can be made to library routines 
that use global variables (such as printf()). 

2. If you are using string or floating-point constants in C source, you’ll usually need to use 
the C compiler’s -b option to put those constants in the code segment (rather than 
generating global variables). 

3. You must use Link’s -rt option to specify the code resource type (such as ' wdef * , 

* init 1 , and so on) and the resource ID. 

4. Because most stand-alone code resources are called as if they were Pascal procedures, 
you must declare the main procedure with the Pascal keyword in C. 

5. You must use Link’s -m option to specify the entry point for the code resource if you 
want dead-code-stripping (see “Dead Code” in the hint section that follows). The 
procedure that is the main procedure for the stand-alone code resource must be the 
first procedure in the source file, and that source file’s object file must be the first file 
in Link’s list of object files to link. In the case of MPW C, you must make the main 
entry point the first function in your file (including all finciude files) if your main 
entry point is not named “main” or if it is named “main” but is of type Pascal, as 
required for a CDEF. 

6. If you need to place all of your object modules in one resource (as in the case of a 
CDEF), use Link’s -sn and -sg option to combine several segments into one segment. 
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♦ Dead code 


Given an entry point to a module, the linker loads object files and creates a 
table of all references reached from that point. The table, called a Directed 
Acyclic Graph, is a tree of all reachable modules. It tracks every single module 
going into a link. For example, 500 modules may be submitted to linking when 
only 100 of them will actually be used by the final linked object. The remaining 
400 modules cannot be reached by references stemming from the main entry 
point and are therefore considered dead code. 

Here's how to use Link's -m option with main modules: 

When you link a • code ■ resource with ID equal to zero (that is, a normal 
application), you must specify a main module with Link's -m option or specify a 
module in one of the object files included with the link. 

When you link any other type of resource (such as a • drvr • or • code • resource 
with an ID other than zero), the linker doesn't require a main module. 

However, you can specify a main module by using the -m option or by 
specifying Main at assembly time. Then, If there is a main module, the linker 
strips out unreachable modules, that is, dead code. If there is no main module 
going into a link, then the linker does not remove dead code. In that case, 
whatever libraries you submit to the linker will be included in their entirety. 

In some cases, for instance, code to be used in a ROM, you might not have a 
single entry point; there might be a number of possible entry points. In such 
cases you want to be careful to submit only the modules that will actually be 
needed by your program. ♦ 


Here is a sample CDEF written in C and Pascal that draws boxes: 

/* File LinesCDEF.c 

Copyright Apple Computer, Inc. 1988 
All rights reserved. 
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/* This file implements a control definition proc for drawing boxes. */ 


#include 

finclude 

tinclude 


<Types.h> 
<QuickDraw.h> 
<Controls.h> 


#define CurrentA5 *((long *)0x904) 

#define GrayPat (** ((Pattern **)CurrentAS) - 0x18) 


pascal long BoxControl (short varCode, 

ControlHandle theControl, 

short message, 

long param) 

{ 

if (message == drawCntl && (*theControl)->contrlVis) { 
FrameRect(&((*theControl)->contrlRect)); 

} else if (message == testCntl) { 

return PtlnRect(*(Point *)&param, 

&(*theControl)->contrlRect) && 

((*theControl)->contrlHilite != 255); 

} 

return 0; 

} 


The makefile rules to build the above sample into a program called Application 

look like this: 

Application ff LinesCDEF.c.o 
Link -rt CDEF=258 3 

-m BOXCONTROL 3 
-sn "Main=Lines" 3 
LinesCDEF.c.o 3 
-o Application 

Here is the same sample CDEF code written in Pascal: 

{ File LinesCDEF.p 

Copyright Apple Computer, Inc. 1988 
All rights reserved. 


{ This file implements a control definition proc for drawing boxes. } 

UNIT LinesCDEF; 

INTERFACE 

USES 

Memtypes, QuickDraw, OSIntf, Toollntf; 

IMPLEMENTATION 
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FUNCTION BoxControl (varCode: 


INTEGER; 


theControl: 

message: 

param: 


ControlHandle; 

INTEGER; 

LONGINT) : LONGINT; 


BEGIN 


BoxControl := 0; 

IF (message = drawCntl) AND (theControl'"'" .contrlVis <> 0) THEN 
FrameRect (theControl'"'". contrlRect) 

ELSE IF message = testCntl THEN 

BoxControl := ORD4(PtlnRect(Point(param), 
theControl'"'".contrlRect) AND 


(theControl'"'".contrlHilite <> 255)); 


END; 


END 


Here are the makefile rules to build the above sample into a program called Application: 


Application ff LinesCDEF.p.o 


Link -rt CDEF=258 3 

-m BOXCONTROL 3 
-sn "Main=Lines" 3 
LinesCDEF.p.o 3 
-o Application 


Building a desk accessory or driver 

Putting together a desk accessory or driver in languages other than assembly language 

requires two steps: 

1. link your driver code with the DRVRRuntime library (this must appear first) and with 
any other libraries you need. The object code is linked into a code resouce of type 

• drvw *, an intermediate form of the standard * drvr* resource. (The DRVRRuntime 
library is the header code for operating desk accessories that cannot be created in C 
or Pascal. See the section The DRVRRuntime Library” later in this chapter.) 

2. Use the resource compiler, Rez, to create the final driver file. That is, compile the 
linked • drvw resource into a standard • drvr • resource, using the 'drvw* type 
declared in :RIncludes:MPWTypes.r, together with any other resources your desk 
accessory may require. 

You then install your desk accessory in the System file by using the Font/DA Mover. 

Figure 8-3 illustrates the process of building a desk accessory or other driver. 
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■ Figure 8-3 Building a desk accessory with DRVRRuntime 



♦ Note: Of course, its always possible to create a desk accessory directly in assembly 
language, without using DRVRRuntime. 
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Linking a desk accessory or driver 


These rules must be observed to link a driver or desk accessory: 

■ Link’s -rt option must be specified. The -rt option indicates the link of a desk 
accessory or driver and sets the resource type and ID. (The default, if no -rt option is 
specified, is to output • code 1 resources beginning with resource ID 0.) 

■ The code must be in a single segment (that is, no jump table is constructed). You can 
map code from several segments into a single segment with the -sg or -sn options. 

■ Desk accessories written in Pascal or C must be linked with DRVRRuntime.o, which 
should appear first in the list of object files. 

For example, the following command links the sample desk accessory file Memory.c.o, 

placing the output in the file Memory. (This output is the intermediate ' drvw * resource, 

which must be converted into a * drvr' resource as explained in the next section.) 

Link -rt DRVW=0 9 

-sn Main=Memory 9 

"{Libraries}"DRVRRuntime.o # must appear first 9 

Memory.c.o 9 

"{CLibraries}"CRuntime.o 9 
"{CLibraries}"CInterface.o 9 
-o Memory.DRVW 

This command has these results: 

■ The -rt option sets the output resource type to * drvw • and the resource ID to 0. 

♦ Note: This ID must match the ID specified in the $$resource statement in the 
Rez input file. Note also that any additional resources “owned” by the desk 
accessory must observe a special numbering convention, as described in the 
chapter “Resource Manager* of Inside Macintosh. 

■ The -sn option combines the segment Main into the segment Memory. 

■ The specified files are linked. The DRVRRuntime.o library must be the first object file 
in the link list. This ordering ensures that the main entry point in CRuntime.o is 
overridden by the DRVRRuntime.o entry point. (A linker warning will call attention to 
this requirement unless you suppress it with the -w option.) The main entry point in 
CRuntime.o cannot be used for desk accessories. 
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♦ An easy way to make sure all the code is in one segment 

As mentioned in the preceding list of instructions, you must keep your code in a 
single segment when linking a desk accessory or driver. Use the -sg option 
without an equal (=) sign. For example 

Link -rt DRVW=09 
-sg Memory9 

"{Libraries}" DRVRRuntime... ♦ 


A Important Desk accessories must not call routines that use global variables, and 
therefore are less likely to need routines from the Pascal, C, and 
specialized libraries listed in Table 8-1. In a correct link, the linker's 
progress information will report “Size of global data area: 0,” and “No 
data initialization.” If global data is somehow allocated, the link will 
succeed, but the desk accessory will not run correctly, a 


The desk accessory resource file 


The last step in constructing a desk accessory or driver is to put together the DRVR header 
with the linked code. The following example of a resource compiler (Rez) input file shows 
how this is done: 


tinclude "Types.r" 

#include "MPWTypes.r" 
type 'DRVR 1 as f DRVW'; 

#define DriverlD 12 /* The number must be in the range [12...26] */ 


resource 'DRVR* (DriverlD, "\0x00Memory", purgeable) { 


/* OK to float around, not saving 
ProcPtrs */ 

/* Yes, give us periodic Control calls */ 
/* No special requirements */ 

/* DA*s do only Control calls */ 


/* Wake up every 5 seconds */ 

/* This DA only handles update events */ 
/* This DA has no menu */ 

/* This isn't used by the DA */ 




dontNeedLock, 

needTime, 
dontNeedGoodbye, 
noStatusEnable, 
ctlEnable, 
noWriteEnable, 
noReadEnable, 

5*60, 

updateMask, 

0 , 

"Memory", 

$$resource("Memory.DRVW", 'DRVW', 0) 
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The header information contains the details of the desk accessory’s event mask, menu ID, 
and so on. (See the chapter “Device Manager* of Inside Macintosh and the file 
MPWTypes.r for information about the format of a 'drvr' resource.) The SSresource 
directive then appends the linked object code to the DRVR header where it belongs. 

If your desk accessory has any owned resources, such as • str#' or 1 wind » resources, you 
can add them to your desk accessory’s resource compiler input. 

To build the desk accessory resource, use the Rez command to compile the resources you 
have specified, and set the file type and creator for a Font/DA Mover document 

Rez -c DMOV -t DFIL Memory.r -o Memory 

The file type DFIL indicates a document file for the Font/DA Mover; the creator DMOV 
indicates a Font/DA Mover document (the suitcase icon). 

To install a desk accessory, use the Font/DA Mover to place the desk accessory in the 
System file. You can do this from MPW as follows: 

"Font/DA Mover" Memory 

After exiting the Font/DA Mover, you can execute the desk accessory by selecting its 
name from the Apple menu. 


The DRVRRuntime library 

This section documents the DRVRRuntime library and describes the specifics of writing a 
desk accessory or other driver by using MPW and MPW Pascal or MPW C. If you are using 
assembly language, you don’t need DRVRRuntime. (See Inside Macintosh for details on 
creating a desk accessory.) Because a desk accessory is a special case of a driver, all of 
the information in this chapter applies to both. You should already be familiar with the 
following: 

■ “Writing Your Own Desk Accessories” in the chapter “Desk Manager* of Inside 
Macintosh 

■ The chapter “Device Manager” of Inside Macintosh (for information about * drvr ' 
resources, and so on) 

■ “Building a Desk Accessory or Driver* earlier in this chapter 

For information about the actual routines used in Pascal, C, or assembly language, see the 
appropriate MPW language reference manual. 
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A desk accessory is a • drvr * resource whose resource name begins with a null character 
($00). ' drvr ' resources reside in the System file. Desk accessories have traditionally 
been written in assembly language, partly because of the peculiar 'drvr' resource format 
used for desk accessories. Setting up the * drvr • layout header, passing register-based 
procedure parameters, and coping with the nonstandard exit conventions of the driver 
routines have made it difficult to implement desk accessories in higher level languages. To 
overcome these difficulties and to simplify the task of writing a desk accessory in Pascal 
or C, MPW provides the following: 

■ The library DRVRRuntime.o, which contains the “glue” for setting up your open, prime, 
status, control, and close routines. 

■ The resource type • drvw •, declared in {RlncludesjMPWTypes.r. The ' drvw * resource 
is an intermediate form of the • drvr' resource and contains constants that point to 
the addresses of the driver routines in DRVRRuntime.o. 

The DRVRRuntime library contains a main entry point that overrides the main entry point 
in CRuntime.o or in your Pascal or assembly-language source. The DRVRRuntime entry 
point contains driver glue that sets up the parameters for you, calls your routines, and 
performs the special exit procedure required for a desk accessory to return control to the 
system. Your routines perform the actions of the desk accessory, such as opening a 
window and responding to mouse clicks in it. 

The resource compiler input (resource description file) for your desk accessory includes 
the details of your desk accessory header, such as its driver flags, event mask, menu ID, 
and driver name. The driver is built by coercing the intermediate 1 drvw * resource to a 
resource of type ’drvr' , which is the format required for desk accessories. Your 
resource description file also specifies resources for any strings, windows, and menus used 
in your desk accessory. (For an example of such a resource description file, see The Desk 
Accessory Resource File” earlier in this chapter.) 

Using DRVRRuntime.o has several advantages: 

■ No assembly-language source code is required. 

■ The resource compiler is an integral step in the build process, permitting the easy 
addition of a desk accessory menu or other owned resources. 

■ The programmer's interface to the open, prime, status, control, and close routines uses 
standard calling conventions. Each function returns a result code which is passed back 
to the system. 

■ The DRVRRuntime glue handles the proper exit conventions. (Drivers have peculiar 
exit conventions, requiring immediate calls to exit via an RTS instruction, but non- 
immediate calls to jump to the iODone routine—these exit procedures cannot be 
expressed in C or Pascal.) 
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Together, the DRVRRuntime library and the 1 drvw 1 resource form the dispatch 
mechanism to your driver routines. The next section describes the structure of your driver 
routines. 


What your routines need to do 

To write a driver, you need to write five functions named DRVROpen, DRVRPrime, 
DRVRStatus, DRVRControl, and DRVRClose. 

♦ Pascal note: In Pascal, you’ll need to write a unit that declares these five functions in 
your interface. 

Each of these functions is declared to use Pascal calling conventions, so that the 
DRVRRuntime library is available for use by both C and Pascal programmers. (See the 
appropriate language reference manual for details.) 

The calling sequence for all five driver routines is the same: The parameter ioPB is the 
pointer to the driver’s I/O parameter block (passed from the system in register AO), and 
dcti is the pointer to the driver’s device control entry (from register Al). The function 
returns a result code, which DRVRRuntime puts in register DO. This result code is a Pascal 
integer (C short). Desk accessories always return a result code of 0. 

For example, here is the Pascal declaration for your DRVROpen routine: 

FUNCTION DRVROpen (ctlPB: ParxnBlkPtr; dCTl: DCtlPtr) : OSErr; 

Types ParmBikPtr and DCtlPtr are declared in the file OSIntf.p. Type OSErr is 
declared in the unit Types. 

In C, write the routines like this: 

pascal OSErr 
DRVROpen(ctlPB,dCtl) 

CntrlParam *ctlPB; 

DCtlPtr dCtl; 

{ 

return(resultCode); 

} 

Types CntrlParam and DCtlPtr are declared in the file Devices.h. Type OSErr is a 
short and is defined in Types.h. 
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Desk accessories only: The body of the desk accessory code resides in your routines 
DRVROpen, DRVRControi, and DRVRCiose. Your routines DRVRPrime and 
DRVRStatus are never called by the system, but the DRVRRuntime library expects them 
to be present anyway—they cannot be omitted. It is sufficient to declare them and have 
them simply return 0. 


Programming hints 

In the current release of MPW, global data is not available for use by desk accessories. 
That is, variables declared outside your functions cannot be used. In particular, the 
following language constructs reference the global data area and cannot be used: 

Asm DATA directives 

Pascal UNIT variables 

C static or extern variables 

Also note that QuickDraw globals cannot be used directly. Furthermore, you cannot call 
library functions that use any of these things. (Look for the linker message “No global data 
was allocated.”) 

Typically, C and Pascal programmers allocate global storage from the heap and use 
• str# • resources for string constants. (In MPW Pascal, constants are allocated as part of 
the code module in which they appear. The same effect can be obtained in MPW C by 
using the *b option.) If you need to allocate global data from the heap, you can declare a 
record containing all of the global variables you need. In your DRVROpen routine, you 
should allocate memory from the heap with the size of this record and store its handle in 
the dctistorage field of the device control entry. Then, to reference an element in the 
record, you can use this handle to reference the global variable you want to use. 
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Sample desk accessory 

A sample desk accessory, Memory, is included in the Examples folders for assembly 

language, C, and Pascal. This desk accessory has the following features: 

■ It displays the current amount of free space in both the application heap and the 
system heap. 

■ It displays the number of free bytes on the default volume, along with the name of the 
default volume. 

■ It performs these operations every 5 seconds, so that you can see how your memory 
conditions change. 


Modifying the Build menu and makefiles 


The Directory and Build menus are implemented as AddMenu commands and scripts. This 
lets you customize these menus to serve your own specific needs. In addition, the 
makefiles created by using the Create Build Commands menu command (script 
CreateMake) can be modified as your scripts grow in complexity. See Chapter 3 for a 
description of the Directory and Build menus. 


Variables 

The Shell variable {Program} is used to remember the name of the most recendy built 
program. It is set by the Create Build Commands menu command and by each of the Build 
menu commands. {Program} is used as the default program name for the Build menu items. 


CHAPTER 8 The Build Process 259 









Scripts 


The following scripts implement the Directory and Build menus. Two of these are 
supported by Commando dialogs, as noted. These scripts are located in the Scripts 
folder. Each is documented in detail in Part II. 

DirectoryMenu 

Create the Directory menu 

SetDirectory 

Set the current directory. (Commando dialog available.) 

BuildMenu 

Create the Build menu 

CreateMake 

Create a program makefile. (Commando dialog available.) 

BuildProgram 

Build the selected program 

BuildCommands 

Display the commands required to build the selected program 

Files 


Commands in the Directory and Build menus may create the following files: 

<Prograrn>. make 

Makefile containing build commands for program 

<Progratti> .makeout 

Build instructions for current build 

{MPWlMPW.Errors 

Diagnostic output from commands run from menus 


UserStartup 


The Directory and Build menus are installed by scripts from the UserStartup file. The 
commands listed below should be in UserStartup. In addition to creating the Directory 
and Build menus, they create the aliases needed to support the Directory menu. 

DirectoryMenu '(Files -d -i "{MPW}"Examples:= || Set Status 0) > 
Dev:Null' 'Directory' 

BuildMenu 

The parameters to DirectoryMenu become the initial list of directories in the Directory 
menu. You can replace or augment the Examples directories with your favorite list of 
directories. 
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Modifying the makefiles 


As the complexity of your program increases, you can modify the makefile created by the 
Create Build Commands menu command. You might add new dependencies, specify 
compiler and linker options, and so on. The Build menu command will continue to build 
the program, using the modified instructions. 


Include dependencies 

You may want to modify a makefile created by the Create Build Commands menu 
command, if you need to overcome the limitations of the CreateMake script. Makefiles 
created by CreateMake do not include dependencies on include files or Pascal uses 
files. If you plan to change the include or uses files, consider modifying the makefile 
to express these dependencies. 

For example, assuming that the C source file Count.c includes the header file Utilities.h, 
add the following dependency rule to the file Count.make: 

Count.c.o f Utilities.h 

No build rules are required; just add the dependency rule. Several include or uses files 
can be listed in the same dependency rule, or separate rules can be used for each 
dependency. Don’t forget to specify the directory for files located in another directory. 


Library object files 

Makefiles created by CreateMake link your program with the selected libraries listed on 
the CreateMake command page in Part n. The libraries are selected according to the 
language or languages in which your program is written and according to the program type 
(application, tool, desk accessory). 

If your program calls routines in a library that is not automatically included in the build 
commands, then modify the makefile to add that library. The library’s name should be 
added in two places: in the dependency rule immediately before the Link command (if 
you expect to modify the library), and in the list of libraries in the link command itself. 

If you consistently need to add the same library to your makefiles, you can modify the 
CreateMake script to include it automatically in the dependency and build rules. 
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Chapter 9 Make 


The make tool enables you to keep track of all of the components of a 
program and their relationships to each other. When one component of a 
program is modified or updated, Make lets you automatically update all other 
parts of the program that depend on it These updates may be such things as 
compiles, assemblies, links, and resource compiles. 

Make reads a makefile that describes the dependencies of the various 
components of a program and outputs commands on the basis of those 
dependencies. This section describes how to write a makefile and use Make. (The 
Make command and command-line options are described in Part II.) ■ 
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Format of a makefile 


A makefile is a text file that describes dependency information for one or more target 
files. A target file is a file to be rebuilt; it depends on one or more prerequisite files that 
must exist or be brought up-to-date before the target can be rebuilt For example, an 
application depends on its source file or files, a number of library files, and resource files. 
If any of a target’s prerequisite files are newer than the target, then the target needs to be 
rebuilt. 

A target’s prerequisites may themselves be targets with their own prerequisites, and so on. 
A target that is not a prerequisite of any other target is called a root A makefile may have 
one or more roots. 

A makefile can include dependency rules, variable definitions, and comments. Table 9-1 
summarizes the syntax of a makefile, and the sections following the table describe this 
syntax in more detail. 
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■ Table 9-1 


Makefile summary 


Syntax rules 

Description 

targetFile... f [prerequisiteFile...] 

[ ShellCommands...] 

Dependency rule, with or without build commands 

This rule means that targetFile depends upon 
prerequisiteFile. If any of the prerequisites are 
newer than the target, the subsequent Shell 
commands are output so that the target can be 
made up-to-date with respect to its prerequisites. 

Important: Build commands must begin with a 
space or tab. 

targetFile... ff [prerequisiteFile ...] 

Dependency rule, requiring its own set of build 
commands 

ShellCommands... 

.[suffix] f .suffix 

Default rule (specifies suffix dependencies) 


ShellCommands... 

targetDirectory :... / searchDirectory :... 

Directory dependency rule (used with default rules) 


variableName = stringValue 

# comment 

[name] 

'...*, a 

dRetum 

Variable definition 

Comment 

Variable reference 

Quotes (as in the Shell) 
line continuation character 


♦ Note: Use Option-F to obtain the / character. 

♦ Note: Makefile physical input lines may not exceed 255 characters. Logical input lines 
(made up of one or more physical input lines continued with the continuation 
character) may be of arbitrary length. 
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A makefile for the sample Pascal application (Sample) is shown below: 

### Variable Definitions ### 

Libs = "{Libraries}"Interface.o 3 

"{Libraries}"Runtime.o 3 
"{PLibraries}"Paslib.o 
### Dependency Rules ### 

Sample ff Sample.r # Sample depends on Sample.r 

Rez Sample.r -a -o Sample 

Sample ff Sample.p.o # Sample depends on Sample.p.o 3 

Sample.r # and Sample.r 

Link Sample.p.o 3 
{Libs} 3 
-o Sample 

Sample.p.o f Sample.p 
Pascal Sample.p 

Sample makefiles are contained in the Examples folder (introduced in Chapter 2). 


Dependency rules 

A dependency rule specifies the prerequisite files of a given target file, together with a 
list of the commands needed for building the target file. These commands will be written 
to standard output if any one of the prerequisite files is newer than the target file or if the 
target doesn’t exist. The general form of a dependency rule is 
targetFile... f [prerequistieFile...] 

[ ShellCommands...] 

The first line is called the dependency line. It consists of one or more target file names, 
followed by the / (Option-F) character (meaning “is a function of”), followed by a list of 
prerequisite files separated by blanks or tabs. Make looks at the modification dates of 
the prerequisite files (and their prerequisites, if any) and decides whether the target needs 
to be rebuilt. 

Because a target’s prerequisites may themselves be targets with their own prerequisites, 
the investigation of prerequisites is recursive and “bottom up.” Thus, commands to 
rebuild lower-level targets are issued, if necessary, before the dependency rule determines 
whether higher-level targets need to be rebuilt. 

All subsequent lines that begin with a space or tab are build command lines. These are 
Shell commands that will be output if the target needs updating. (When Make writes these 
command lines to standard output, the initial space or tab is omitted.) If the dependency 
rule omits the build commands, the rule expresses only the target’s dependencies. The 
build lines for the target are assumed to be supplied by another rule. 
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For example, 

Sample.p.o f Sample.p 
Pascal Sample.p 

The first line in the example is a dependency rule for the Pascal object file Sample.p.o. 

This rule states that Sample.p.o depends on the source file Sample.p. 

The second line is the associated build command line. If Sample.p is newer than 
Sample.p.o, or if Sample.p.o doesn’t exist, the command Pascal sample.p is 
written to standard output 

The target is built according to that set of build rules whenever it is out-of-date with 
respect to any of its prerequisites. If no build commands are specified for a dependency 
line, the build commands are taken from one of the target’s other dependency rules, or 
from default rules if no build rules were specified for the target. 

If you specify more than one single-/ dependency line for a target, then the target 
depends on all the prerequisite names on all the lines. However, only one sequence of build 
commands may be specified for each target. 

More than one target filename can appear on the left-hand side of an “/ rule.” Each target 
file on the left-hand side depends on all of the files listed on the right side (and has the 
same build commands, if specified). If more than one target file is specified, it’s exacdy 
as if a separate dependency rule had been given for each target. The built-in Make variable 
{Targ) has the value of the current target. 

♦ Note: Typically, you’ll have more than one target on the left side of an / rule only when 
expressing dependencies, so you won’t include any build rules. If you do supply build 
rules, you must write them in a generic fashion by using the {Targ} variable because 
each target is built independently. Contrary to what the syntax might suggest, 
multiple targets on the left side of an / rule do not imply that Make builds all targets by 
a single application of the build rules. Therefore you cannot use this construct to 
express dependencies in which a tool has more than one output file. 


You can also write a dependency rule with an abstract target, that is, a target that is not 
actually built but represents a collection of items. A rule with an abstract target has no 
build rules, just dependencies; the target on the left side of the / rule does not exist. It 
serves merely to trigger the dependencies for the prerequisite files on the right side of the 
/ rule. Thus, if your makefile represents several different roots that could be built, they 
can be collected into a single abstract target that (when it is built) triggers the builds for 
all the separate objects. That is, 

All f ABC 
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Double/ dependency rules 

Double-/ dependency rules are slightly different from the standard single-/ rules. 
Syntactically, a double-/ dependency rule is the same as a single-/ rule, except that ff is 
used in place of/. The difference in use is that more than one double-/ rule is expressed 
for an individual target and that each double-/ rule requires its own set of build 
commands. Here is a simple example: 

TargetFile ff A B D 
build commands-1 

TargetFile ff CD 
build commands-2 

If the target is out-of-date with respect to one or more dependency sets, each of the 
corresponding sets of build commands will be output (in the order they appear in the 
makefile). That is, if TargetFile is out-of-date with respect to both A and C, then both 
sets of build commands are output. (In single-/ rules, only one set of build commands can 
be specified for any one target.) 

If TargetFile is out-of-date only with respect to B, then only the first set of build 
commands is output If TargetFile is out-of-date with respect to D, then both sets of 
build commands are output, because D appears in the dependency sets for both. In other 
words, the same file can appear as a prerequisite in more than one double-/ 
dependency set. 

Here is a more realistic example showing how double-/ rules are typically used to 
separately control the building of different components of the same file: 

App ff foo.c.o bar.c.o 

link foo.c.o bar.c.o . . . -o App 
App ff App. r 

rez App.r ... -a -o App 

Use double-/ rules only when you have more than one action to take in building a file, and 
when you want the actions to be independent (that is, triggered by different 
dependencies and not always occurring together). Double-/ rules are useful for separately 
building code and resources, as shown in the makefile for Sample. (For more examples, see 
the sample makefile at the end of this section.) 

The build commands may be left off a double-/ rule if they are to be supplied by default 
rules. If build commands are left out of more than one double-/rule for the same target, 
Make applies the default rules only to the first empty set. 


CHAPTER 9 Make 269 





Default rules 


Default rules express dependencies between pairs of files whose names are the same but 
whose suffixes differ. They have the following form: 

.[suffixl] f suffix2 
ShellCommands... 

♦ Note: The period must be present directly in front of the suffix for a default rule to be 
recognized. The period is taken as part of the suffix. 

Default rules are powerful because many specific dependencies and build commands can 
be expressed by a single rule, thereby eliminating the need to specify many similar 
dependency rules. Make has built-in default rules for assemblies and for C and Pascal 
compiles. You need to specify only the dependencies not covered by default rules. 

For example, in its simplest form a default rule for C compiles might be 
.c.o / .c 

C {defaultl.c 

In this example the built-in Make variable {default} represents the common part of the 
filenames matching the rule. The C compiler will be run on the source file with a “.c” suffix 
and will produce an object file with a “c.o” suffix. 

Default rules are applied only when no build commands have been given for a particular 
target You can augment the default rules for a particular file by using additional 
dependency rules, so long as these dependency rules do not include build commands. 

If you are planning to have an object file built by a default rule, there is no need to express 
the dependency on the source file because it is implied by the default rule. Only 
additional dependencies, such as includes, need to be expressed explicitly. 

Make applies default rules only if the file implied by the right-side suffix of the rule exists, 
or if Make can arrive at a file that exists by farther applications of default rules. 

If the left side of a default rule has more than one period (or component), there is the 
possibility that more than one default rule applies. For example, you may have a default 
rule for building “.o’ files and another for building “.c.o” files. Because Make tries to apply 
default rules by matching the longest suffix first, the “.c.o” rule is tried first. 

Default rules of the form 
. / .suffix 

specify dependencies between files with any name and files with the same name followed 
by the given suffix. 
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♦ Note: Default rules of this fonn slow down Make processing, because the empty left 
side of the rule causes it to match against all filenames. 

Built-in default rules 

A compiled or assembled object file is dependent on its source file. This dependency is 
typically handled by the built-in default rules. 

Additional object file dependencies may result from other units that you use or refer to in 
your source file—these may be include files, C header files, or Pascal USES files. These 
additional dependencies can be expressed by dependency rules with no build line 
component, leaving the build lines and object-to-source dependency implied by the 
default rules. 

The data fork of the Make tool contains the following built-in default rules: 

.a.o f .a 

{Asm} {AOptions} {DepDir}{Default}.a -o {TargDir}{Default}.a.o 
.c.o f .c 

{C} {COptions} {DepDir}{Default}.c -o {TargDir}{Default}.c.o 
. p . o f .p 

{Pascal} {POptions} {DepDir}{Default}.p -o {TargDir}{Default}.p.o 

{Asm}, {Pascal}, and {C} are built-in Make variables. Their initial values are 
{Asm} Asm 

{Pascal} Pascal 

{C} C 

{AOptions}, {POptions}, and {COptions} are initially null; you can customize the built-in 
default-rule build commands by defining these variables in your makefile. For instance, 
you might want to specify the location of your Pascal Include files by adding an -i 
pathname option to the default rules by a variable definition of the form 

POptions= -i pathname 

Or you may want to indicate the use of a different C compiler by changing the value of the 
{C} variable. 

You can redefine the {Asm}, {Pascal}, {C}, {AOptions}, {POptions}, and {COptions} 
variables. Variable definitions can be overridden in your makefile, on the command line 
(with Make’s -d option), or by an exported Shell variable. See “Variables in Makefiles” later 
in this chapter. 
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If you cannot sufficiently customize the default rules by assigning to these built-in 
variables, you can override any of the default rules by placing your own versions of the 
default rules in your makefile. 

{Default} is another built-in variable; its value is the common part of the filenames 
matched by a default mle (defined dynamically when Make applies the default rule). The 
{Default} variable is what allows you to write a generic default rule without referring to a 
specific filename. Because its value is set dynamically by Make, its value cannot be 
overriden in your makefile. 

{DepDir} and {TargDii} are built-in Make variables that allow default rules to work with the 
target and prerequisite files in different (or the same) directories: 

{DepDir} The directory component of the prerequisite name 

{TargDir} The directory component of the target name 

♦ Note: {DepDir} and {TargDir} have values only when used in the build commands of 
default rules for which directory dependency rules were applied. In all other cases 
these variables evaluate to the null string so that they won’t interfere with the normal 
behavior of default rules. Directory dependency rules are explained in the section that 
follows. 


Directory dependency rules 

Normally, default rules work only within a single directory; that is, the target and 
prerequisite files will have the same directory component because the default rules change 
only the suffixes of the filenames. Directory dependency rules allow default rules to be 
applied across directories. Just as default rules imply changing a filename suffix between a 
target filename and a prerequisite filename, directory dependency rules imply changing 
the directory prefix of the filenames. Directory dependency rules have the form 

targetDirectory:... f searchDirectory:... 

Directory dependency rules are identified by dependency names that end in colons (that 
is, directory names). For example, 

ObjFiles: f SrcFiles: 

The above rule, together with the standard default rules, would mean, for example, that 
ObjFiles: name.c.o depends on SrcFiles: name.c. See the working example at the end of 
this chapter. 
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No build commands may be given for a directory dependency rule. More than one 
directory name may appear on either side of the rule. The current directory can be 
specified by a single colon (:) on either side of a directory dependency rule. 

Directory dependency rules are applied only during the processing of default rules. If 
Make is applying a default rule and encounters a target name with a directory component, 
Make checks for a directory dependency rule for that directory. If one exists, Make tries 
prerequisite filenames with the directory prefixes given on the right side of the rule. The 
names are tried in the order they appear in the rule; thus more than one directory name on 
the right side of a directory dependency rule constitutes a list of directories to search. 


♦ Note: If default rules are meant to be applied from a directory A: to a directory B: and 
also within A: (that is, from A: to A:), then A: should appear on both the left and right 
sides of the directory dependency rule. For example, 

A: f A: B: 


Variables in makefiles 

You can use exported Shell variables and built-in Make variables within makefiles. You can 
also define variables within a makefile or on the Make command line. MPW Shell variables 
are described in Chapter 5. 


Shell variables 

Make automatically defines exported Shell variables before it reads the makefile, so you 
can use Shell variables in dependency lines and build commands. 

Shell variables in dependency lines are expanded because they are typically filenames or 
parts of a file. Shell variables in build rules pass through unexpanded so that the Shell will 
be able to process and expand them. 

If Make doesn’t recognize a variable reference in a build command line, the build line is 
left unchanged when it is output so that it can be processed later by the Shell. 
(Unidentified variables in dependency lines are reported as errors.) 
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A Warning Exported Shell variables override Make variables with the same names. 

An attempt to redefine a Shell variable in the makefile results in a 
warning message. ▲ 


Defining variables within a makefile 

Variable definitions are makefile entries of the form 
variableName = stringValue 

Subsequent appearances of {variableName} are replaced by stringValue. Any leading or 
trailing blanks or tabs are removed from the variable definition. You can use line 
continuations to make a stringValue arbitrarily long. 

When a stringValue is continued across lines, a single blank replaces any comments, 
blanks, or tabs at the end of the continuation line and at the beginning of the line after the 
continuation. Thus, variable values can conveniently contain lists of files. Note that 
variable values may contain references to other variables. 

One common use of variables is to provide parameters to the directory portion of 
filenames so that you can easily adapt a makefile to different directory setups. Another 
use is to create a list of filenames that will be used in more than one place. 

♦ Note: Make variables are not expanded until they are used in dependency lines or until 
generated in a build line. Thus, you must define any variables appearing in 
dependency lines somewhere previously in the makefile because variables in 
dependency lines are expanded immediately to produce filenames. You can define 
variables in build lines anywhere in the makefile because variables in build lines are not 
expanded until after the build lines are generated (that is, after the entire makefile has 
been read). 


You can define a variable on the command line with the Make option -d; this option 
overrides any definition of the variable within the makefile, thus allowing the definition in 
the makefile to function as a default 

♦ Note: Values of Make variables may not contain the ASCII characters 0 or 1. 
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Built-in Make variables 

The following built-in Make variables have values that are dynamically assigned (and that 
cannot be overridden) as Make generates the build commands: 

{Targ} The complete filename of the target on the left side of the 

dependency rule whose build commands are being processed. 

{NewerDeps} A list of the names of all of the target’s direct prerequisites that 
were newer than the target; that is, the files that caused the 
target to be out-of-date. 

These built-in variables can be used only in build command lines because they have no 
value when dependency lines are processed. They cannot be overridden. 

When default rules are applied, the following variables are also defined: 

{Default} The common part of the filenames matched by a default rule 
{TargDir} The directory component of the target name 

{DepDir} The directory component of the prerequisite name 

♦ Note: When expanding the built-in variables {Targ}, {NewerDeps}, fTargDir}, {DepDir}, 
and {Default} in build commands, Make automatically quotes their values, if 
necessary, because they will represent filenames or parts of filenames. Don’t quote 
them yourself. 


Quoting in makefiles 

The Make command supports several of the Shell’s quoting conventions. Quoted items 
can appear in dependency lines, variable definition lines, and build command lines. The 
following quotation characters are used: 

d Quotes the subsequent character; that is, the d is removed and the subsequent 

character is taken to be a literal character (except when 3Retum is used at the end 
of a line as a continuation character). 

'...' Quotes the enclosed string. The single quotation marks are removed. 

Quotes the enclosed string, but {...} variable references are expanded, and the 
escape character d is processed. Die double quotation marks are removed. 
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Quotation characters are processed as follows: 

■ In dependency lines and in the name part of variable definitions, quotation literalizes 
the quoted characters (useful for expanding file or variable names). 

■ On the right side of variable definitions, quoted items are passed through “as is,” so 
that the quoting will take effect when the variable is expanded. 

■ In build command lines, quoted items are passed through as is, so that the quoting will 
take effect when the build commands are executed by the Shell. 


Line continuation character 

Like Shell commands, dependency and variable definition lines can be continued over 
more than one line by using dRetum. 9Retum causes the 9, any blanks preceding the 9, the 
return, and any leading blanks on the next line to be replaced with a single space. 
Comments at the ends of such continued lines do not comment out the continuation 
character. 


Comments in makefiles 

The number sign (#) indicates a comment. Everything from the # to the end of the line is 
ignored. Comments always end at the next return, even if the return is preceded by a 9. 

Comments may appear in dependency lines, variable definitions, and build command 
lines, or on lines by themselves. Comments in build command lines are passed through to 
standard output where they are processed as comments by the Shell. 


Executing Make’s output 

Make generates a set of commands, which must be executed separately to perform the 
actual updates. You can automatically execute Make’s command output by calling Make 
from a Shell script The simplest form of such a script consists of the two commands 

Make {"Parameters"} > MakeOut 
MakeOut 
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The first command executes Make, using the parameters passed to the script (See the 
description of the {"Parameters"} variable in Chapter 5 under “Variables.”) Output (that is, 
build commands) is redirected to the file MakeOut. The second line of the script executes 
MakeOut. 


The order in which Make builds targets 

Make builds the top-level target and its prerequisite subtargets in a recursive, “bottom 
up” fashion. The top-level target (or targets) may be specified on the Make command 
line. If no target is specified on the command line, then Make builds the first target 
appearing on the left side of a dependency rule in the makefile (that is, the default top- 
level target). 

The prerequisites of the top-level target (and subtargets) are also investigated in a 
recursive, “bottom up” order, starting with the first prerequisite in the target’s 
prerequisite list. After the first prerequisite (and its own prerequisites) have been 
investigated, the target’s next prerequisite is investigated. The next prerequisite will be 
the next one mentioned in the current dependency rule or in the next dependency rule in 
the file that has the same left-side target. 

Thus, the important orderings within a makefile are: the first target mentioned (the 
default top-level target) and the order of prerequisites for any given target Otherwise, 
the order in which targets are mentioned is not important 

Please note, however, that once a target has been investigated by Make it is not revisited, 
even if it appears somewhere else in the top-level target’s prerequisite dependency 
hierarchy. In other words, while a file may appear as a prerequisite of a number of program 
components, Make will rebuild it only once (if necessary) when it is first encountered in 
the recursive “bottom up” traversal of the dependency hierarchy. 

Remember that a makefile may have one or more top-level targets (or roots), that is, it 
may describe how to build more than one object. (The -r option will identify all the 
roots.) Running Make will rebuild only the targets you specify on the command line. If no 
targets are specified, Make will rebuild the default targets. 
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Debugging makefiles 


When Make doesn’t seem to be doing what you expect, the next step is to debug your 

makefile. The following procedures are helpful in debugging makefiles: 

1. Use Make’s -v option to generate verbose diagnostic output. This output tells you 
which files don’t exist, which files are up-to-date, which files need rebuilding, and why 
they are out-of-date. It also points out which files don’t have build rules and are thus 
assumed to be artificial targets. (Targets that are abstract and not really built. See, for 
example, Note 8 in the Make example that follows this section.) 

2. Use Make’s -s option to show the structure of your target’s dependency relations. This 
option displays the complete structure of dependencies, including those generated by 
default rules. A target (or subtarget) that doesn’t appear or that has no prerequisites 
may indicate a typographical error in the dependency line for that target (or in the line 
for one of the targets that depend on it). A target that appears at the wrong level in 
the dependency graph indicates an error in your dependency specification. 

3. Use the -u option to find unreachable targets. These may be parts of your target 
dependencies that did not get connected to the rest of the dependency hierarchy 
because of a bad or mistyped rule. 


Problems due to co mman d generation before execution 

Make generates commands that must be separately executed to perform the actual 
updates. Because Make must determine what build commands to generate before any 
targets are actually built, the possibility of “phase errors” exists; that is, unexpected 
behavior may occur when generated commands alter the assumptions that Make used to 
determine whether targets were out-of-date. (You won’t experience these problems unless 
you have build commands that do things such as deleting files that Make thinks are 
already up-to-date.) 
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Problems with different specifications for the same file 

You’ll experience problems with Make if you use different pathname specifications for 
the same file (that is, pathnames with different degrees of volume and directory 
qualification). Make uses the name strings exactly as encountered in dependency lines, so 
different name strings will result in different entries. (This is done for the sake of 
performance—no calls are made to the file system, except to inquire about the date of 
targets that are supposed to be built.) If there is more than one name specification for 
the same file, each name results in a different Make target, and the resulting dependency 
relations will be wrong. 


Problems with default rules 

An error message may appear saying that no rules were available to build something that 
should have been covered by a default rule. This situation may result from any one of the 
following problems: 

■ The default rule may not have matched against anything, and was thus not applied; for 
example, the default rule 

.p.o f .p 

cannot be applied if the .p file does not exist either in the file system or in the 
makefile dependency specification. 

■ There may be a typographical error in the filename, so that the default rule could not 
be applied. You should be able to detect such errors by inspecting the output of 
Make’s -s and -v options. 

■ There may be a typographical error in a default rule that was given in the makefile, in 
which case you may not see any dependencies generated by the rule when you use the 
*s option on the Make command line. 


An example 

This section lists the makefile used to build an experimental version of the Make tool 
itself (represented in this makefile by the MakeX target). A series of explanatory notes 
follows die listing. These notes describe in detail a number of the Make features that were 
used. 
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#################### Variables ##################### 


ToolDir 

ObjDir 

MakeUses 


MakeObjs 


Libs 


LinkOpts 


SourceFiles = 


{Boot}ToolUnits: 

:Ob j: 

{ToolDirJMacInterfaces. p. o 
{ToolDir}MemMgr.p.o 
{ToolDir}SymMgr.p.o 
{ToolDir}Utilities.p.o 
{ToolDir}IOInterfaces.p.o 
{ToolDir}CursorCtl.p.o 
{ToolDir}ErrMgr.p.o 
{PInterfaces}IntEnv.p 
{PInterfaces}MemTypes.p 
{PInterfaces}QuickDraw.p 
{PInterfaces}OSIntf.p 
{ObjDirJMake.p.o 
{ToolDir}Stubs.a. o 
{ToolDir}CallProc.a. o 
{ToolDir}Utilities. p.o 
{ToolDir}Utilities. a. o 
{ToolDir}IOInterfaces.p.o 
{ToolDir}IOInterfaces.a.o 
{ToolDir}MemMgr. p. o 
{ToolDir}MemMgr.a.o 
{ToolDir}SymMgr.p.o 
{ToolDir}SymMgr.a.o 
{ToolDir}CursorCtl. p. o 
{ToolDir}CursorCtl. a. o 
{ToolDir}ErrMgr.p.o 
{ToolDirJMacInt. a. o 
{ToolDir}MacInterfaces.p.o 
{Libraries}Runtime.o 
{PLibraries}PasLib. o 
{Libraries}Interface.o 


See note 1 

d See note 2 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 

3 


-w # no warnings (for duplicates due to Stubs.a.o) 

See note 3 


Make.p 3 
DefaultRules 3 
Makefile 


########### Default Rule Customization ############ 


POptions = 
{ObjDir} f 


-i {Boot}ToolUnits: 

: # directory dependency rule 


See note 4 
See note 5 
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################ Dependency Rules ################## 

MakeX ff {MakeObjs} {Libs} See note 6 

Link {LinkOpts} -p -b -o MakeX 9 

-t MPST -c "MPS " 9 

{MakeObjs} {Libs} >LinkMsgs 

MakeX ff defaultRules 

Duplicate -d defaultRules MakeX -y # copy default rules into Make's data fork 


MakeX ff 

Rez Make.r -o MakeX -a 


Make.r 


# Make's Commando resource 


MakeX ff 

SetFile MakeX -m . -d . 


{MakeObjs} {Libs} defaultRules 
#set last-mod and creator dates 


{ObjDir}Make.p.o // Make.p 

Save Make.p >Dev:Null I I Set Status 0 


See note 7 

#save source before compile if changed 


{ObjDir}Make.p.o ff {MakeUses}#will be augmented by default rules 

See note 8 


{ToolDir}MacInterfaces.p.o 


{ToolDir}MemMgr.p.o 

{ToolDir}SymMgr.p.o 

{ToolDirutilities.p.o 
{ToolDir}IOInterfaces.p.o 


Backup 

Duplicate -y 


MakeSrc: 


Restore 

Duplicate -y MakeSrc:** 
Listings 

Print -h -r -Is .85 -s 8 
Echo "Last listings made 


f {PinterfacesJMemTypes.p 

See note 9 

{Pinterfaces}QuickDraw.p 
{PInterfaces}OSIntf.p 
{PinterfacesJToolIntf.p 
{PInterfaces}PasLibIntf.p 

f {ToolDirutilities.p.o 

{ToolDir}MacInterfaces.p.o 9 

{PInterfacesJMemTypes.p 

/ {ToolDir}MemMgr.p.o 

{PInterfaces}MemTypes.p 

f {Pinterfaces}MemTypes.p 

/ {ToolDirJUtilities.p.o 

{ToolDir}MacInterfaces.p.o 9 

{Pinterfaces}MemTypes.p 

f 

tbackup to Sony 


: trestore from Sony 

f {SourceFiles} 

-b -hf helvetica -hs 12 {NewerDeps} 
'Date'" >Listings 


See note 10 


See note 11 
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Notes on Make’s makefile 


These notes are referenced in the preceding example. 

1. The exported Shell variable {Boot}, used in the definition of {ToolDir}, is automatically 
defined by Make when invoked. 

2. Several variables—{MakeUses}, {MakeObjs}, {Libs}, and {SourceFiles}—are used for lists 
of filenames. This is a convenience because the lists are used in several places later in the 
makefile; it also helps to reduce errors. Note that you can temporarily remove any file 
from the list by placing a comment character at the beginning of the line for the file. 

3. The {LinkOpts} variable is used to specify linker options (and is used only once). This 
usage is handy because the definition in the makefile functions as a default that can be 
overridden from the command line with the -d option, as in 

Make -d LinkOpts='-w -1 >Map' 

4. This directory dependency rule allows the MakeX tool’s objects and sources to be in 
different directories and yet be built by the built-in default rules. In particular, 

Make.p.o will be in the :Obj: directory while Make.p is in the current directory. Note 
that for this device to work, Make.p.o must appear with the object directory prefix. 
Thus it appears in the makefile as {ObjDir}Make.p.o. 

5. The {POptions} definition gives a value to one of the variables used in the default rules, 
customizing the built-in default rules for Pascal compiles for this particular makefile. 

6. The four sets of// rules for MakeX (an experimental version of the Make tool) handle 
(a) the Make link (which creates MakeX’s code resources), (b) the copying of the 
default rules to MakeX’s data fork (Make reads the built-in default rules from its own 
data fork), and (c) the setting of the creation and modification dates. The link will 
take place only if the MakeX objects or libraries change. The default rules will be copied 
only if the rules have changed. The resource compiler will rebuild Make’s Commando 
resource only if Make.r has changed. And the setting of the dates will take place if either 
of the first two rules was activated. (Note that the fourth rule has the union of the 
dependency relations of the first two.) 

7. The two sets of// rules for Make.p.o control the compilation of the main source for 
Make, with some interesting side effects. The first// rule saves the Make source before 
it is compiled, only if the source file has changed. The second// rule does the actual 
compile. Note that this last rule has no explicit build commands, so it will be augmented 
by the built-in default rules, which will add a dependency relation (on the source file 
Make.p), and will supply the actual build commands for the compile. 

8. The {ObjDir} prefix is necessary for the directory dependency rule to take effect. It 
allows the object and source to be in different directories. 
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9. The dependency rules for Maclnterfaces, MemMgr, SymMgr, Utilities, and IOInterfaces 
describe dependencies between various utility units used by Make. Several 
dependencies on library interface files are given. Dependencies among the utility units 
themselves are described by indicating a dependency on the object files of the lower- 
level (predecessor) units. These dependencies could have been expressed as 
dependencies on the source files of the lower-level units (because it is the source files 
that are read in a Uses list). However, expressing these dependencies on the object files 
has the nice property of ensuring that the lower-level units have been successfully 
compiled before the higher-level units are built. 

10. The Backup, Restore, and Listings targets are additional roots (top-level targets) in 
Make’s makefile, and thus represent other things that can be built besides MakeX itself. 
Note that the Backup and Restore targets do not actually get built by their build rules; 
they are thus artificial targets 2 nd will always generate build commands if they are 
specified on the Make command line. Note also that they do not have any dependency 
relations. 

11. The build rules for the Listings target demonstrates the use of the {NewerDeps} variable. 
The prerequisite of Listings is a list of the Make source files. The first build command 
prints the {NewerDeps} files. {NewerDeps} contains the names of the prerequisites that 
are newer than the target, that is, the source files that have changed since listings were 
last made. The last line of the build rules simply writes the current date into a file called 
Listings, which is the name of our target—this action results in a file that remembers 
when listings were last made. (Writing the datecvf into the file is unnecessary but 
convenient; the Echo itself is enough to change the file’s last-modified date.) 


♦ Note: There are several implicit builds that are generated as needed by the default 
rules. For example, the {MakeObjs} variable includes several assembly-language object 
files. Because {MakeObjs} appears as a prerequisite of the link step, these assemblies 
are generated, if necessary, before the link. 
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Chapter 10 


More About Linking 


This chapter supplements the information in the section “Linking” in 
Chapter 8 and in the description of the Link command in Part n. This chapter will 
be more useful after you’re familiar with Chapter 8 and the major MPW tools and 
when you are ready to optimize your programs or build procedures. 

Use Link, the MPW linker, to combine a group of MPW object files (such as the 
output of the compilers) into a Macintosh-executable resource, such as an 
application, desk accessory, driver, or MPW tool. ■ 

Contents 

Link functions 287 
Segmentation 288 

Segments with special treatments 289 
Controlling the numbering of code resources 290 
Resolving symbol definitions 291 

Multiple external symbol definitions 291 
Unresolved external symbols 292 
Building applications with more than 32K of global data 292 
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32-bit references—MPW Assembler 293 
Linker location map 294 

Map entries for the global data segment 295 
Optional map formats for compatibility 295 
Optimizing your links 296 
Library construction 296 

Using Lib to build a specialized library 297 
Removing unreferenced modules 298 
Guidelines for choosing files for a specialized library 299 
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Link functions 


After a source file has been assembled or compiled into an object file, it contains 

■ Object code (relocatable machine language). 

■ Symbolic (named) references to all identifiers whose locations were not known at 
compile time. (These include references to routines from separate compilations and 
libraries, and references to global variables.) 

The linker performs the following functions: 

■ Sorts code and data modules into segments, by segment name. (Within a segment, 
modules are placed in the order in which they occur in the input files.) The -sg and -sn 
options allow you to change segmentation at link time. 

♦ Note: A module is a contiguous region of memory that contains code or static 
data. A module is the smallest unit of memory that is included or removed by the 
linker. A segment is a named collection of modules. 

■ Omits unused (“dead”) code and data modules from the output file. (These modules 
can be listed with Link’s -uf option, and deleted from libraries with the Lib command’s 
-df option.) 

■ Provides (together with the Segment Loader) a jump table architecture that supports 
relocation of code and data at run time. (See the chapter “Segment Loader” of Inside 
Macintosh for more information about the jump table.) 

■ Constructs jump table entries only when needed, that is, only when a symbol is 
referenced across segments. This means that the jump table will be of minimum size. 

■ Edits instructions to use the most efficient addressing mode. A5-relative (jump table) 
addressing is used across segments, and PC-relative addressing is used within a 
segment. 

▲ Warning If you take the address of a procedure that is within the same 

segment, then, as stated, a PC-relative address is used to generate 
the effective address. (This is the case in MPW C by default, and in 
MPW Pascal when used with the -b option.) If the procedure 
address is stored as a variable (or passed to the tool box), and the 
segment is unloaded, then any routine calling that address will 
transfer control to the wrong place, with the result that the 
program will crash. See Macintosh Technical Note 42. a 
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A Important Note that the -b option in MPW Pascal means that you will use the 
A5 offset to the jump table, rather than the PC-relative address. 
The meaning of the -b option in MPW C is opposite; it forces PC- 
relative addressing and also places strings and constants in the 
same module, a 

■ Provides (with the data initialization interpreter) support for relocation of data 
references at run time. (The data initialization interpreter is the module _DATAINTT 
in the libraries Runtime.o and CRuntime.o.) 

■ Generates a cross-reference listing of link-time (object-level) names (-x option). 

■ Generates a location map for debugging or performance analysis (-map option). 

l ink copies linked code segments into code resources in the resource fork of the output 
file. By default, these resources are given the same names as the corresponding segment 
names. 

If linker errors or a user interrupt cause the output file to be invalid, the linker sets the 
file’s modification date to “zero” (January i f 1904 ,12:00 A.M.). This action guarantees 
that the Make command will recognize that the file needs to be relinked, and that the 
MPW Shell will not run the file. 


Segmentation 


Segmenting a program makes it possible for temporarily unneeded parts of the program 
to be unloaded and purged from memory, thus freeing memory space. You specify the 
name of a segment by placing a directive in your program’s source file. See the 
appropriate lan guage reference manual for information. Each segment is linked into a 
separate code resource. 

♦ Note: For a desk accessory or driver, the code must be in a single segment, and no jump 
table is constructed. Segmentation applies only to applications and MPW tools. 

The linker sorts object code into load segments by name, allowing you to organize your 
source code for clarity and understanding. You can specify the same segment name more 
than once. Link collects code for a given segment name from all of link’s input files and 
places it into a single segment in the output file. 
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A Warning Segment names are case sensitive. For example, “Segl” and “SEG1” are 
not equivalent names. If you aren’t sure about the cases used, you can 
use the linker’s -p option to get a listing. ▲ 

By default, resources created by the linker are given resource names identical to the 
corresponding segment names. Link provides options for combining and renaming 
segments at link time (-sg and -sn). If you don’t specify a segment name before the first 
routine in your file, the main segment name (“Main”) is assumed there. Normally, you 
should give the main segment the name Main. 

By default, segments are limited to 32,760 bytes. This limit ensures compatibility with all 
versions of the Macintosh ROM. Larger segments are allowed with Link’s -ss option. 


♦ Note: Object code is placed in a segment in the order that it’s encountered in the input 
file. For segments larger than 32K, the order is important because PC-relative offsets 
are limited to 32K by MC68000 instructions. 


For more information about segmentation, see the chapter “Segment Loader” of 
Inside Macintosh. 


Segments with special treatments 

When linking a main program, Link creates two segments that don’t appear in the input 
object files: 

■ The jump table (• code • resource, ID=0), which is unnamed. 

■ The global data area (no resource), which is named %GlobalData and appears only in 
the link map file (described below). You can’t change the name %GlobalData at link 
time. 
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There are also two segments that have special conventions: 

■ The segment that contains the main program entry point (' code * resource, ID=1), 
usually named Main. 

■ A segment named %A5init, which contains the initial values for the global data area 
and code that moves these initial values to the global data area. Applications should 
unload this segment before allocating any memory in order to avoid memory 
fragmentation. You can unload the %A5init segment by calling unioadseg with 
the address of entry point _datainit as its parameter. In Pascal, for example, 

UnloadSeg(&_DATAINIT); 

In C, the same call looks like this: 

UnloadSeg((Ptr) JDatalnit); 

In C and Pascal, this call should be the first statement in the application. In assembly 
language the call to UnloadSeg should follow the call to _Datainit. 


Controlling the numbering of code resources 


Normally, you don’t need to worry about which segments are given which resource 
numbers. However, you may want to control the assignment of resource numbers to 
optimize program load time, to implement a specialized code manager, or to match the 
numbering produced by another linker. 

Link creates and numbers code resources based on the order in which it encounters the 
segment names in the command-line parameters and the input object files. If you can’t 
easily predict the order in which the names appear in the object files, you may want to 
force the ordering with command-line options that contain dummy segment-mapping 
directives. For example, the following sequence of linker options forces Main to come 
first, followed by Init, Body, and Terra- 

Link -sn dummyl=Main # must contain the main code module 3 

# or entry point 3 
-sn %A5Init=Init 3 
-sn dummy3=Body 3 
-sn dummy4=Term 3 
„.and so cm 
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The “old” segment names may be either “dummy” names (which don’t appear in the object 
files) or actual mappings, such as the mapping of the %A5init code into the segment 
Init. 

♦ Note: The segment containing the main code module will always be segment #1. 


Resolving symbol definitions 

This section describes how the linker resolves references to symbols. For a more detailed 
discussion of local and external symbols, see Appendix H. 

Symbols in object files are either local or external. A local module or entry point can be 
referenced only from within the file where it is defined. An external module or entry point 
can be referenced from different object files. An entry point is a location (offset) within 
a module. (The module itself is treated as an entry point with offset zero.) A reference is a 
location within one module that will contain the address of another module or entry. 

If the linker finds a symbol, it will first try to match the symbol to a local symbol in the 
same file. If the name cannot be located, the linker will then look for it externally. (An 
exception to this procedure is described in the “Record” section of Appendix H.) 


Multiple external symbol definitions 

If the object files contain more than one definition for an external symbol, the first 
definition is used, and all references are treated as references to the first definition. This 
lets you selectively override entry points in libraries so that you can substitute new 
versions of code. When subsequent definitions are encountered, a warning is generated. 

♦ Note: If you override a module, then all succeeding entry points within the overridden 
module also disappear. Therefore be sure that any other referenced entry points in the 
overridden module are also defined in the new, overriding module. 
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Unresolved external symbols 


Occasionally, you may find that an external symbol is unresolved because a reference was 
generated with case sensitivity set one way, whereas the definition was generated with 
different case rules. When this happens, you can avoid recompiling by using the Link 
option -ma (module alias). Whenever Link encounters an unresolved symbol, it checks the 
list of module aliases in an attempt to resolve it. 


Building applications with more than 32K of global data 

To permit your application to use more than 32K of global data, use the -m option of the 
MPW Pascal and MPW C compilers. The -m option generates code that causes global data 
references to be 32-bits. You should be aware that the code for 32-bit references is larger 
and slower than the code for 16-bit references. 

Follow these steps: 

1. Use the -m option when you compile Pascal or C files that reference “far” data. All 
Pascal units and the Pascal main (if any) in the program must be compiled using either 
-m or -n (see the note for Pascal users below). 

2. Implement 32-bit references in assembly language when necessary (see the note for 
Assembler users below). 

3. Use the linker’s -srt option. This option instructs the linker to sort data modules into 
near and far groups, placing all 16-bit referenced global data as close to A5 as possible, 
and all only-32-bit-referenced data farther away. Thus, any data with a 16-bit 
reference is forced to within 32K of A5. You can also use die -ss size option to 
suppress the linker’s warning about code or data segments larger than 32K. 

The -srt option alters the usual ordering of global data (that is, it is no longer governed 
strictly by Link command line order). 
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32-bit references—MPW Pascal 

If any Pascal unit in a program is compiled with -n or -m, then all Pascal units (including 
the Pascal main) must be compiled with either the -m or -n options. For units that don’t 
need 32-bit references, specify -n. 

Historically, Pascal global data was held in a single module (with the same name as the 
unit) and referenced by offsets into the module. The -n option generates a named module 
per data item (as in C). The -m option implies the -n option. 

If you compile one unit (UNTTA) with -n and another (UNITB) without -n, and if both 
units reference data declared in the other unit, this situation results: 


Unit 

has variables 

compiled with 

exports 

references 

UNITA 

foo, bar 

-nor-m 

foo, bar 

baz, bletch 

UNITB 

baz, bletch 

nothing 

JJNITB 

.UNITA (+offset) 


UNITA references data modules in UNITB using variable names (which are never defined), 
while UNITB references a module called _UNITA, which is never defined. The link will fail. 


32-bit references—MPW Assembler 


In assembly language you must explicitly code 32-bit references when you want to avoid 
fixing a data module to within 32K of A5. For the MC68000, you could write something 
like this: 

IMPORT LONGDATA:DATA 

MOVE.L indirect (PC), DO ; [4/7/9 clocks] offset -> scratch register 

MOVE .x (A5,DO.L), cfest ; [ea: 3/6/7 clocks] access variable (PEA,etc.) 


indirect: 


DC.L LONGDATA ; 32-bit offset of data 


In code that is intended to run only on a MC68020, you can do this: 

MACHINE MC68020 

IMPORT LONGDATA:DATA 

MOVE .x ((LONGDATA).L,A5) , dest ; move to destination (or PEA) 

; [ea: 11/15/25 clocks] 
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♦ Note: The MC68020 code, while smaller, runs more slowly than the MC68000 code 
shown above if we ignore the possible impact of the temporary register required (11 
versus 7 clocks best case, 15 versus 13 clocks cache case, and 25 versus 16 clocks worst 
case). 


Linker location map 

If you specify the Link option -map, Link writes a location map to standard output. The 
map contains information about segments and where modules are located in the 
segments. (See note later in this section about optional formats.) 

For each code segment, the linker writes a segment map that looks like 

Segment "Main" size=$0326 rsrcid=l JTindex=$0000 #JTEnts=$0001 


COMPACTMEM 

$0000 

size=$0018 

file="Interface.o” 

SAVE0RETA1 

$OOOA 



SAVERETA1 

$oooc 



SAVE 

$000E 



SAVEO 

$0014 



NEWPTR 

$0018 

size=$000C 


CMain 

$0024 

size=$0036 

JT=$0000(A5) 

__RTInit 

$005A 

size=$01F4 

file="CRunTime.o" 

exit 

$024E 

size=$0020 


_RTExit 

$026E 

size=$0050 


c2pstr 

$02BE 

size=$0032 


p2cstr 

$02F0 

size=$001E 


main 

$030E 

size=$0018 



■ The first line indicates the segment’s name, size, and resource id. One or more module 
or entry point entries follow the segment description. 

■ JTindex is the number of the segment’s first jump table-entry. 

■ JTEnts indicates the number of jump-table entries belonging to the segment. 

■ A name of “% ? Anon” indicates that the module or entry point is anonymous (was not 
given a name by the language processor). 

■ The first number following the name is the module or entry point’s segment offset. (If 
the segment is a * code • segment, the segment offset doesn’t include the 4-byte 
segment header required by the Segment Loader.) 

■ If the entry is for a module, the module’s size is indicated. 

■ If the module or entry point has a jump-table entry, the A5-offset of that entry is 
indicated. 

The name of the object file that the module came from is printed every time the object 

filename changes. That is, if subsequent modules come from the same object file, the 

object filename is not printed again (which reduces the size of the location map). 
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Map entries for the global data segment 


When linking an application or tool with global data, Link writes a map of the global data 
segment that looks like: 


Segment "%GlobalData" 
#0001 
_ArgC 
_ArgV 
_EnvP 
StandAlone 
_IntEnv 
_SAGlbls 
foo 


size=$0106 
-$0106(A5) 
-$0106(A5) 
-$0102(A5) 
-$OOFE(A5) 
-$00FA(A5) 
-$00F6(A5) 
-$00C2(A5) 
-$0004(A5) 


size=$000C 


size=$0004 

size=$0034 

size=$00BE 

size=$0004 


hasContents 

hasContents 

hasContents 

hasContents 


■ The first line summarizes the global data segment, giving only its name and size. 

■ Subsequent lines indicate the A5-offsets of variables. 

■ If a line describes a module, the module’s size is indicated; if there is no size present, 
the line describes an entry point within the module immediately above. 

■ If the data module contains initialized data, the word * hasContents • follows the 
size. 


As for code segments, the name of the object file the data module came from is printed 
whenever the object file name changes. 


Optional map formats for compatibility 

The options -1, -la, and -If produce a linker map in an obsolete format This format has 
been retained only for compatibility with the MPW Performance Tools, which currently 
read the map files to determine module locations. Tools should not depend on the format 
of the location map, as it is likely to change in future releases of MPW. (If tools need 
information about module locations, they should read symbolic information files 
produced with the -Sym option. Documentation on the Sym file format is available 
separately from Developer Technical Support.) 
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Optimizing your links 


Because of the complexity of the linker's functions, the Link step is often the longest 
single step during incremental rebuilding of your program. The following steps can 
substantially speed up Link’s performance: 

■ Use a RAM cache. Link must open and close many object files. Experience has shown 
that large links run up to four times faster when you use a RAM cache of 64K or more on 
machines with at least 1 megabyte or more of RAM. (Use the Control Panel desk 
accessory to check your RAM cache settings. If you change the setting, you must 
restart the system to have the new setting take effect.) 

■ Use the lib utility to combine input files. You can use the Lib command to reduce the 
number of input files. Using lib can give a 10-15 percent improvement in linking 
speed. See “Library Construction” later in this chapter. 

■ Eliminate unneeded files. You can eliminate unneeded input to the linker by heeding 
the warning “File not needed for link,” and removing such files from the link. This 
means customizing your link lists, rather than relying on a generic makefile for linking. 

■ Eliminate unneeded references. You can also eliminate unneeded input by using Lib to 
remove unreferenced modules. Experience has shown that producing a specialized 
library file can increase Link’s speed by as much as 40 percent. See the next section, 
“Library Construction.” 


library construction 

The Lib tool enables library construction by allowing you to combine object code from 
different files and languages into a single object file. For example, you can combine 
assembly-language code with C or Pascal. The Lib tool was used for this purpose in 
constructing the libraries distributed with MPW. 

The tool lib and its options are described in Part II. This section explains some aspects 
of using Lib. 
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Lib reorganizes the input files, placing the combined library file in the data fork of the 
output library file. By default, the library output file is given type ' ob j ' and creator 
*mps Lib’s output is logically equivalent to the concatenation of the input files, except 
for its optional renaming, resegmentation, and deletion operations, and the possibility of 
overriding an external name (as in link). Lib doesn’t combine modules into larger modules, 
nor does it resolve cross-module references. This limitation guarantees that the output of 
a link that uses the output of Lib is the same as that of a link using the “raw” files 
produced by the compilers and assembler. 


♦ Why lib can speed up your links 

Object files processed with Lib result in significantly faster links than the ‘raw* 
object files produced by the compilers and assembler. There are several reasons for 
the speed improvements: 

■ Code and Data modules are separated into different sections, and Code 
modules are further sorted by segment name. These actions improve the 
performance of Link, which must sort input modules into output code 
resources. 

■ All of the named symbols in the object file are gathered into a single Dictionary 
area at the start of the file. This makes the output file smaller and simplifies the 
processing needed by Link to resolve references. 

■ When several object files are combined, multiple instances of a symbol 
definition are replaced by a single definition. Again, this makes the output file 
smaller and simplifies the processing by Link. ♦ 


Lib correctly handles file-relative scoping conventions, such as nested procedures in 
Pascal, static functions in C, or ENTRY names in assembly language; that is, it never 
confuses references to an external symbol with references to a local symbol of the same 
name, even if the two symbols are in two files combined with Lib. 


Using Lib to build a specialized library 

Each of the language libraries has files that you may or may not need to link with, 
depending on the functions your program calls. (See Appendix A.) Once you determine 
which files are needed for linking a particular program, you can greatly improve the 
performance of subsequent links by combining libraries into a single specialized library 
file. In building a specialized library, you can use Lib to 
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■ change segmentation (with the -sg and -$n options) 

■ change the scope of a symbol from external to local (with the -dn option) 

■ delete unneeded modules (with the -dm option) 

Lib’s renaming, resegmentation, and deletion operations give you precise control over 
external names, the contents of library files, and the segmentation of object code. To use 
these features, you may need to review some of the material in Appendix H to understand 
how modules and entry points are represented in object files. The DumpObj command is 
also useful in exploring the contents and structure of the library files provided with MPW. 

Removing unreferenced modules 

You can eliminate unneeded input to Link by using Lib to remove unreferenced modules. 
You can determine the number of unreferenced modules from Link’s progress information. 
(Use the -p option.) Link reports the total number of symbols read, as well as the number 
of active symbols (that is, the symbols in the output), and the number of visible symbols 
(that is, the symbols requiring jump-table entries)—for example, 

155 active and 54 visible entries of 714 read. 

The difference between the total read and the number of active symbols is the number of 
unreferenced (and unneeded) symbols. Most of these unreferenced symbols represent 
standard library functions that your particular program doesn’t require. 

Unreferenced modules can be removed in three steps: 

1. Use Link’s -uf option to produce a file containing the unreferenced names. 

2. Use the -uf file produced by link as the input to Lib, using the Lib option -df to 
produce a specialized library that contains only the modules that your program 
requires. 

3. Use the output of Lib as the input to subsequent links. 
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Guidelines for choosing flies for a specialized library 

The choice of files to include in a specialized library file is largely dictated by stability 
issues. Files that are unlikely to change for many builds are the best candidates. Stable 
files include the library files provided by Apple for the ROM interfaces and for language 
support. Files that are under development are best left as single files. 

Should you find it necessary to change one of the component files of a specialized library, 
you don’t always need to rebuild the specialized library immediately. You can simply 
include the newer version of the object file in the link list by placing it before the 
specialized library file that contains the older version. You’ll get some warning messages 
about duplicate symbols, but all references will be correctly moved to the first definition 
encountered by Link. Later, after the file is stable again, you can rebuild the library. 
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Chapter ll Resource Compiler and Decompiler 


This chapter explains the use of the resource compiler (Rez) and resource 
decompiler (DeRez). The command line syntax for Rez and DeRez is explained in 
Part II. The general syntax for resource description files is summarized in 
Appendix D. You can build a resource in text form by using Rez, or graphically by 
using the application ResEdit. Complete background information on Macintosh 
resource files is given in the chapter “Resource Manager” of Inside Macintosh. ■ 
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About the resource compiler and decompiler 


The resource compiler, Rez, compiles a text file (or files) called a resource description 
file and produces a resource file as output. The resource decompiler, DeRez, decompiles 
an existing resource, producing a new resource description file that can be understood by 
Rez. Figure 11-1 illustrates the complementary relationship between Rez and DeRez. 


■ Figure 11-1 Rez and DeRez 



Rez can combine resources or resource descriptions from a number of files into a single 
resource file. Rez can also delete resources or change resource attributes. Rez supports 
preprocessor directives that allow you to substitute macros, include other files, and use if- 
then-else constructs. (These are described under the heading “Preprocessor Directives” 
later in this chapter.) 
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Resource decompiler 

The DeRez tool creates a textual representation of a resource file based on resource type 
declarations identical to those used by Rez. (If you don’t specify any type declarations, 
the output of DeRez takes the form of raw data statements.) The output of DeRez is a 
resource description file that may be used as input to Rez. This file can be edited in the 
MPW Shell, allowing you to add comments, translate resource data to a foreign language, 
or specify conditional resource compilation by using the if-then-else structures of the 
preprocessor. You can also compare resources by using the MPW Compare command to 
compare resource description files. 

♦ Note: MPW includes a tool, ResEqual, which directly compares resource files. The 
Pascal source for ResEqual is located in the PExamples folder. Also see the MPW tool 
RezDet, described in Part II. 


Standard type declaration files 


Four text files, Types.r, SysTypes.r, MPWTypes.r, and Pict.r, contain resource declarations 
for standard resource types. These files are located in the {RIncludes} directory, which is 
automatically searched by Rez and DeRez (that is, you can specify a file in {RIncludes} by 
its simple filename).These files contain definitions for the following types: 


Types.r 

SysTypes.r 

MPWTypes.r 

Pict.r 


Type declarations for the most common Macintosh 
resource types ('alrt', 'ditl', 'menu', and so on) 

Type declarations for *drvr', 'fond', 'font', *fwid’, 'intl', 
' nfmt ' , and many others 

Type declarations for the MPW driver type ' drvw ' 

Type declaration for PICT resources for debugging PICTs 


Cmdo.r Type declaration for Commando resources 


Using Rez and DeRez 

Rez and DeRez are primarily used to create and modify resource files. Figure 11-2 
illustrates the process of creating a resource file. 
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Figure 11-2 Creating a resource file 



Rez can also form an integral part of the process of building a program. For instance, when 
putting together a desk accessory or driver, you would use Rez to combine the linker’s 
output with other resources, creating an executable program file. (See Chapter 8 for 
details on building desk accessories and drivers.) 
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Structure of a resource description file 


The resource description file consists of resource type declarations (which can be 
included from another file) followed by resource data for the declared types. Note that 
the resource compiler and resource decompiler have no built-in resource types. You need 
to define your own types or include the appropriate “.r” files. 


A resource description file may contain any number of these statements: 


include 

read 

data 

type 

resource 

change 

delete 


Include resources from another file. 

Read data fork of a file and include it as a resource. 

Specify raw data. 

Type declaration—declare resource type descriptions for 
subsequent resource statements. 

Data specification—specify data for a resource type declared in 
a previous type statement. 

Change the type, ID, name, or attributes of existing resources. 
Delete existing resources. 


Each of these statements is described in the sections that follow. 


A type declaration provides the pattern for any associated resource data specifications 
by indicating data types, alignment, size and placement of strings, and so on. You can 
intersperse type declarations and data in the resource description file as long as the 
declaration for a given resource precedes any resource statements that refer to it. An error 
is returned if data (that is, a resource statement) is given for a type that has not been 
previously defined. Whether a type was declared in a resource description file or in an 
include file, you can redeclare it by providing a new declaration later in a resource 
description file. 

A resource description file can also include comments and preprocessor directives: 

■ Comments can be included any place white space is allowed in a resource description 
file, by putting it within the comment delimiters /* and 7. Note that comments do 
not nest. For example, this is one comment: 

/* Hello /* there */ 

Rez also supports C++ style comments: 

type 'tost* { // the rest of this line is ignored 

■ Preprocessor directives substitute macro definitions and include files, and 
provide if-then-else processing before other Rez processing takes place. The syntax of 
the preprocessor is very similar to that of the C-language preprocessor. 
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Sample resource description file 


An easy way to leam about the resource description format is to decompile some erfcring 
resources. For example, the following command decompiles only the 'wind 1 resources in 
the Sample application, according to the type declaration in {RIncludes}Types.r. 

DeRez Sample -only WIND Types.r > DeRez.Out 

Note that Rez automatically finds Types.r in {RIncludes}. After executing this command, 
DeRez.Out would contain the following decompiled resource: 

resource 'WIND 1 (128, "Sample Window") { 

{64, 60, 314, 460}, 
documentProc, 
visible, 
noGoAway, 

0x0, 

"Sample Window" 

}; 


Note that this statement is identical to the resource description in the file Sampler, which 
was originally used to build the resource. This resource data corresponds to the following 
type declaration, contained in Types.r: 


type 'WIND* { 


rect; 

integer documentProc, dBoxProc, plainDBox, 
altDBoxProc, noGrowDocProc, 
zoomProc=8, rDocProc=l6; 
byte invisible, visible; 
fill byte; 

byte noGoAway, goAway; 
fill byte; 

unsigned hex longint; 

pstring 

/* title */ 


/* boundsRect */ 

/* procID */ 


/* visible */ 

/* goAway */ 

/* refCon */ 

Untitled = "Untitled" 


}; 


Type and resource statements are explained in detail in the reference section that follows. 


Resource description statements 

This section describes the syntax and use of the seven types of resource description 
statements available for the resource compiler: include, read, data, type, 

delete, change, and resource. 
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Syntax notation 

The syntax notation in this chapter follows the conventions given in the preface of this 
book. In addition, the following conventions are used: 

■ Words that are part of the resource description language are shown in the Courier font 
(following the conventions used in documentation of the C language) to distinguish 
them from surrounding text. Rez is not sensitive to the case of these words. 

■ Punctuation characters such as commas (,), semicolons (;), and quotation marks (' 
and") are to be written as shown. If one of the syntax notation characters (for 
example, [ or ] ) must be written as a literal, it is shown enclosed by “curly” single 
quotation marks ('...’); for example, 

bit st ring T length ']’ 

In this case, the brackets would be typed literally—they do not mean that the 
enclosed element is optional. 

■ Spaces between syntax elements, constants, and punctuation are optional; they are 
shown for readability only. 

Tokens in resource description statements may be separated by spaces, tabs, returns, or 
comments. 


Special terms 


The following terms represent a minimal subset of the nonterminal symbols used to 
describe the syntax of commands in the resource description language: 


Term Definition 


resource-type 

resource-name 

resource-ID 

ID-range 


long-expression 

string 

word-expression 

EX'M 


♦ Note: Expression is defined later in this chapter under “Expressions.” 


A full syntax definition can be found at the end of this chapter and in Appendix D. 


Include—include resources from another file 

The include statement lets you read resources from an existing file and include all or 
some of them. 
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Syntax 

An include statement can take the following forms: 

■ include file [ resource-type [‘ (’ resource-name I ID[:IDJ‘) ’] ] ; 

Read the resource of type resource-type with the specified resource name or resource 
ID range in file. If the resource name or ID is omitted, read all resources of the type 
resource-type in file. If resource-type is omitted, read all the resources in file. 

■ include file not resource-type ; 

Read all resources not of the type resource-type in file. 

■ include file resource-typel as resource-type2; 

Read all resources of type resource-typel and include them as resources of resource- 
type2. 

■ include file resource-typel * (’ resource-name 1 ID[:ID]‘) ’ 

as resource-type2 ‘ (’ ID [, resource-name] [, attributes... ] ‘) 

Read the resource of type resource-typel with the specified name or ID range in file, 
and include it as a resource of resource-type2 with the specified ID. You can optionally 
specify a resource name and resource attributes. (Resource attributes are defined 
below.) 

Some examples follow: 

include "otherfile"; /* include all resources from the file */ 
include "otherfile" 'CODE'; /* read only the CODE resources */ 
include "otherfile" 'CODE' (128); /* read only CODE resource 128 */ 


AS resource description syntax 

The following string variables can be used in the as resource description to modify the 
resource information in include statements: 


$$Type 

$$ID 

$$Name 

$$Attributes 


Type of resource from include file 
ID of resource from include file 
Name of resource from include file 
Attributes of resource from include file 


For example, to include all * drvr 1 resources from one file and keep the same information 
but also set the sysheap attribute: 


INCLUDE "file" 'DRVR* (0:40) AS 

•DRVR* ($$ID, $$Name, $$Attributes | 64) ; 

The $$ Type, $$ID, $$Name, and $$Attributes variables are also set and Ip gal 
within a normal resource statement. At any other time the values of these variables are 
undefined. 
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Resource attributes 


You can specify attributes as a numeric expression (as described in the chapter “Resource 
Manager” of Inside Macintosh), or you can set them individually by specifying one of the 
keywords from any of the following pairs: 


Default 

Alternative 

Meaning 

appheap 

sysheap 

Specifies whether the resource is to be loaded into 
the application heap or the system heap. 

nonpurgeable 

purgeable 

Purgeable resources can be automatically purged by 
the Memory Manager. 

unlocked 

locked 

Locked resources cannot be moved by the Memory 

Manager. 

unprotected 

protected 

Protected resources cannot be modified by the 

Resource Manager. 

nonpreload 

preload 

Preloaded resources are placed in the heap as soon 
as the Resource Manager opens the resource file. 

unchanged 

changed 

Tells the Resource Manager whether a resource has 
been changed. Rez does not allow you to set this 
bit, but DeRez will display it if it is set. 


Bits 0 and 7 of the resource attributes are reserved for use by the Resource Manager and 
cannot be set by Rez, but are displayed by DeRez. 

You can specify more than one attribute by separating the keywords with a comma (,). 


Read—read data as a resource 

The read statement lets you read a file’s data fork as a resource. 

Syntax 

read resource-type ‘ (’ ID[, resource-name] [, attributed')’ file ; 

Description 

Reads the data fork from file and writes it as a resource with the type resource-type and the 
resource ID ID, with the optional resource name resource-name and optional resource 
attributes (as defined in the preceding section). For example, 

read *STR 1 (-789,"Test String",SysHeap,PreLoad) "Test8"; 
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Data—specify raw data 

Use the data statement to specify raw data as a sequence of bits, without any 
formatting. 

Syntax 

data resource-type 1 (’ ZD[, resource-name) [, attributes... ]*)’'{’ 
data-string 

T; 

Description 

Reads the data found in data-string and writes it as a resource with the type resource-type 
and the ID ID. You can optionally specify a resource name, resource attributes, or both. 

For example, 

data 'PICT' (128) { 

$"4F35FF8790000000" 

$"FF234F35FF790000" 

); 


♦ Note: When DeRez generates a resource description, it uses the data statement to 
represent any resource type that doesn’t have a corresponding type declaration or 
cannot be disassembled for some other reason. 


Type—declare resource type 

A type declaration provides a template that defines the structure of the resource data for 
a single resource type or for individual resources. If more than one type declaration is 
given for a resource type, the last one read before the data definition is the one that’s 
used. This lets you override declarations from include files or previous resource 
description files. 


Syntax 

type resource-type [ ‘ (’ ID-rangp 1 ) ’] '{’ 
type-specification... 

T; 
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Description 

Causes any subsequent resource statement for the type resource-type to use the 
declaration { type-specification ...}. The optional ID-range specification causes the 
declaration to apply only to a given resource ID or range of IDs. 

Type-specification is one of the following: 

bitstring [n] 

byte 

integer 

longint 

boolean 

char 

string 

pstring 

wstring 

cstring 

point 

rect 

fill Zero fill 

align Zero fill to nibble, byte, word, or long word boundary 

switch Control construct (case statement) 

array Array data specification—zero or more instances of 

data types 

These types can be used singly or together in a type statement. Each of these type 
specifiers is described in the sections that follow. 

♦ Note: Several of these types require additional fields. The exact syntax is given in the 
sections that follow. 


You can also declare a resource type that uses another resource’s type declaration by 
using the following variant of the type statement: 

type resource-typel [ ‘ (’ ID-range') ’ ] as resource-type2 PC ID 97; 
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Data-type specifications 

A Data-type statement declares a field of the given data type. It can also associate 
symbolic names or constant values with the data type. The data-type specification 
can take three forms, as shown in this example: 

type ' XAMP 1 { /* declare a resource of type ’XAMP' */ 

byte; 

byte off=0, on=l; 

byte = 2; 

}; 

■ The first byte statement declares a byte field; the actual data is supplied in a 
subsequent resource statement. 

■ The second byte statement is identical to the first, except that the two symbolic 
names “off” and “on” are associated with the values 0 and 1. These symbolic names 
could be used in the resource data. 

■ The third byte statement declares a byte field whose value is always 2. In this case, no 
corresponding statement would appear in the resource data. 

Numeric expressions and strings can appear in type statements; they are defined later in 
this chapter under “Expressions.” 

Numeric types: The numeric types (bitstring,byte, integer, longint) are fully 
specified like this: 

[ unsigned] [ radix] numeric-type [ =expr I symbol-definition... ]; 

■ The Unsigned prefix signals DeRez that the number should be displayed without a 
sign—that the high-order bit can be used for data and the value of the integer cannot 
be negative. The Unsigned prefix is ignored by Rez but is needed by DeRez to 
correctly represent a decompiled number. Rez uses a sign if it is specified in the data. 
Precede a signed negative constant with a minus sign (-); $FFFFFF85 and -$7B are 
equivalent in value. 

■ Radix is one of the following string constants: 

hex decimal octal binary literal 

You can supply numeric data as decimal, octal, hexadecimal, or literal data. 

■ Numeric-type is one of the following: 

bitstring' [’length.'] ’ Declare a bitstring of length bits (maximum 32). 

byte Declare a byte (8-bit) field. This is the same as 

bitstring[8]. 

integer Integer (16-bit) field. This is the same as bitstring [16]. 

longint Long integer (32-bit) field. This is the same as 

bitstring[32 ]. 
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Rez uses integer arithmetic and stores numeric values as integer numbers. Rez translates 
booleans, bytes, integers, and longints to bitstring equivalents. All computations are done 
in 32 bits and truncated. 

An error is generated if a value won’t fit in the number of bits defined for the type. The 
valid ranges for values of byte, integer, and longint constants are as follows: 

Type Maximum Minimum 


byte 255 -128 

integer 65,535 -32,768 

longint 4,294,967,295 -2,147,483,648 


Boolean type: A Boolean is a single bit with two possible states: 0 (or false) and 1 (or 
true). (True and false are global predefined identifiers.) Boolean values are declared 
as follows: 

boolean [ = constant I symbolic-value... ]; 

The type boolean declares a 1-bit field; this is equivalent to 
unsigned bitstring[1] 

♦ Note: This type is not the same as a Boolean variable as defined by Pascal. 

Character type: Characters are declared as follows: 
char [ = string I symbolic-value... ]; 

Type Char declares an 8-bit field (this is the same as writing string [ l ]). 

Here is an example: 

type *SYMB* { 

char dollar = percent = 

}; 

resource 'SYMB' (128) { 

dollar 
lu¬ 
string type: String data types are specified like this: 
string-type [‘ [’ length '] ’] [= string I symbol-value...]; 

String-type is one of the following: 
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[hex] string Plain string (no length indicator or termination character is generated). 

The optional hex prefix tells DeRez to display it as a hex string, 
string [ n] contains n characters and is n bytes long. The type char is 
shorthand for String [ 1 ]. 

pstring Pascal string (a leading byte containing the length information is 

generated). Pstring [ n] contains n characters and is n+ 1 bytes long. 
Pstring has a built-in maximum length of 255 characters, the highest 
value the length byte can hold. If the string is too long to fit the field, a 
warning is given and the string is truncated. 

wstring Word string is a very large pstring . Its length is stored in the first two 

bytes. Therefore, a word string can contain up to 65,535 characters. 
wstring[n] contains n characters and is n+2 bytes long. 

cstring C string (a trailing null byte is generated), cstring [ n] contains n -1 

characters and is n bytes long. A C string of length 1 can be assigned only 
the value " ", because cstring [ l ] has room only for the terminating 
null 

Each string type may be followed by an optional length indicator in brackets ([ n]). 

Length is an expression indicating the string length in bytes. Length is a positive number in 

the range 1 < length < 2147483647 for string and cstring, and in the range 1 < length 

< 255 for pstring, and in the range 1 < length < 65535 for wstring. 


♦ Note: You cannot assign the value of a literal to a string type. 


If no length indicator is given, a pstring, wstring, or cstring stores the number of 
characters in the corresponding data definition. If a length indicator is given, the data 
may be truncated on the right or padded on the right. The padding characters for all string 
types are nulls. If the data contains more characters than the length indicator provides for, 
the string is truncated and a warning message is given. 


▲ Warning A null byte within a cstring is a termination indicator and may 
confuse DeRez and C programs. However, the full string, 
including the explicit null and any text that follows it, will be stored 
by Rez as input. ▲ 


Resource description statements: Point and rectangle types: Because points and rectangles 
appear so frequently in resource files, they have their own simplified syntax: 

point [ = point-constant I symbolic-value...]; 
rect [ = rect-constant I symbolic-value...]; 

where 

point-constant = ‘ { ’x-integer-expr, y-integer-expr ‘} ’ 
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and 

rect-constant = ‘ {’integer-expr, integer-expr, integer-expr, integer-expr ‘} ’ 

These type statements declare a point (two 16-bit signed integers) or a rectangle (four 16- 
bit signed integers). The integers in a rectangle definition specify the rectangle’s upper- 
left and lower-right points, respectively. 

Fill and align types 

The resource created by a resource definition has no implicit alignment. It’s treated as a 
bit stream, and integers and strings can start at any bit. The fill and align type 
specifiers are two ways of padding fields so that they begin on a boundary that 
corresponds to the field type. Align is automatic and fill is explicit. Both fin and 
align generate zero-filled fields. 

Fill specification: The fill statement causes Rez to add the specified number of bits 
to the data stream. The fill is always 0. The form of the statement is 

fill fill-size C * [* length ] ’ ] ; 

where fill-size is one of the following strings: 

bit nibble byte word long 

These declare a fill of 1,4,8,16, or 32 bits (optionally multiplied by the length modifier). 
Length is an expression < 2147483647. 

The following fill statements are equivalent: 

fill word[2]; 
fill long; 
fill bit[32]; 

The full form of a type statement specifying a fill might be: 
type 'xres' { data-typespecifications; fin bit [2]; }; 

♦ Note: Rez supplies zeros as specified by fill and align statements. DeRez does not 
supply any values for fill or align statements; it just skips the specified number of 
bits, or until data is aligned as specified. 


Align specification: Alignment causes Rez to add fill bits of zero value until the data is 
aligned at the specified boundary. An alignment statement takes the following form: 

align align-size ; 

where align-size is one of these strings: 

nibble byte word long 
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Alignment pads with zeros until data is aligned on a 4-, 8-, 16-, or 32-bit boundary. This 
alignment affects all data from the point where it is specified until the next align 
statement. 


Array type 

An array is declared as follows: 

[ wide ] array [array-name I ‘[’length]’] '{’array-list 1 }’; 

The array-list, a list of type specifications, is repeated zero or more times. The wide 
option outputs the array data in a wide display format (in DeRez)—the elements that 
make up the array-list are separated by a comma and space instead of a comma, return, 
and tab. Either array-name or [ length ] may be specified. Array-name is an identifier. 

If the array is named, then a preceding statement should refer to that array in a constant 
expression with the $$ count of (array-name) function; otherwise DeRez will treat the 
array as an open-ended array. For example, 

type 'STR#' { /* define a string list resource */ 

integer = $$Countof(StringArray); 
array StringArray { 
pstring; 

}; 

}; 

The $$countof function returns the number of array elements (in this case, the number 
of strings) from the resource data. 

If [length] is specified, there must be exacdy length elements. 

Array elements are generated by commas. Commas are element separators. Semicolons are 
element terminators. In this example, however, it may be a good idea to use semicolons as 
element separators: 

type 'xyzy* { 

array Increment { 

integer = $ $ArrayIndex(Increment); 

}; 

}; 

resource 'xyzy 1 (0) { 

{ /* zero elements */ 

} 

}; 

resource 'xyzy* (1) { 

{ /* two elements */ 

r 

} 

}; 
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resource 'xyzy* (3) { 

} /* two elements */ 

/ / 

j 

}; 

/* The only way to specify one element in an array that has all 
constant elements, is to use a semicolon terminator. 

/* 

resource 'xyzy' (4) { 

{ /* one element */ 

t 

) 

}; 


Switch type 

The switch statement specifies a number of case statements for a given field or fields 
in the resource. The format is: 

switch't’ case-statement... 


where a case-statement has this form: 
case case-name : [ case-body ; 1... 


Case-name is an identifier. Case-body may contain any number of type specifications and 
must include a single constant declaration per case, in this form: 


key data-type= constant 


Which case applies is based on the key value. For example, 


type 'DITL* { /* 

...type specifications... 

switch { /* 

case Button: 

boolean enabled, 

key bitstring[7] = 4; 
pstring; 
case CheckBox: 

boolean enabled, 

key bitstring[7] = 5; 
pstring; 


dialog item list declaration from Types.r */ 

one of the following */ 

disabled; 

/* key value */ 


disabled; 

/* key value */ 


...and so on. 


}; 


}; 
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Sample type statement 


The following sample type statement is the standard declaration for a 'wind * resource, 
taken from the Types.r file: 


type 'WIND'{ 


}; 


rect; 

integer documentProc, dBoxProc, plainDBox, 

altDBoxProc, noGrowDocProc, 
zoomProc=8, rDocProc=16; 
byte invisible, visible; 

fill byte; 

byte noGoAway, goAway; 

fill byte; 

unsigned hex longint; 

pstring Untitled = "Untitled"; 


/* bounds 
/* procID 


/* visible 

/* close box 

/* refCon 
/* title 


*/ 

*/ 


*/ 

*/ 

*/ 

*/ 


The type declaration consists of header information followed by a series of statements, 
each terminated by a semicolon (;). The header of the sample window declaration is 


type 'WIND' 

The header begins with the Type keyword followed by the name of the resource type 
being declared—in this case, a window. You may specify a standard Macintosh resource 
type, as shown in the chapter “Resource Manager” of Inside Macintosh, or you may declare 
a resource type specific to your application. 

The left brace [{] introduces the body of the declaration. The declaration continues for as 
many lines as necessary until a matching right brace} is encountered. You can write more 
than one statement on a line, and a statement may be on more than one line (like the 
Integer statement above). Each statement represents a field in the resource data. Recall 
that comments may appear anywhere where white space may appear in the resource 
description file; comments begin with /* and end with /* as in C. 


Symbol definitions 

Symbolic names for data type fields simplify the reading and writing of resource 
definitions. Symbol definitions have the form 

name= value [, name= value ]... 
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For numeric data, the “= value ” part of the statement can be omitted. If a sequence of 
values consists of consecutive numbers, the explicit assignment can be left out—if value 
is omitted, it’s assumed to be one greater than the previous value. (The value is assumed 
to be zero if it’s the first value in the list.) This is true for bitstrings (and their derivatives, 
byte, integer, and longint). For example, 

integer documentProc, dBoxProc, plainDBox, 

altDBoxProc, noGrowDocProc, 
zoomProc=8, rDocProc=16; 

In this example, the symbolic names documentProc, dBoxProc, plainDBox, altDBoxProc, 
and noGrowDocProc are automatically assigned the numeric values 0,1, 2,3, and 4. 

Memory is the only limit to the number of symbolic values that can be declared for a single 
field. There is also no limit to the number of names you can assign to a given value; for 
example, 

integer documentProc=0, dBoxProc=l, plainDBox=2, altDBoxProc=3, 

rDocProc=16, Document=0, Dialog=l, DialogNoShadow=2, 
ModelessDialog=3, DeskAccessory=l6; 


Delete—delete a resource 

Sometimes you may want to delete a resource without switching to ResEdiL Some 
resource operations, such as those needed by “internationalizing” system disks and 
applications need to translate menu and dialog text, and hence require deleting or 
changing resources. 

Syntax 

delete resource-type [ ‘ ( 'resource-name | ID [: ID ] ‘) ’ ] ; 

Description 

Delete the resource of type resource-type from the output file with the specified resource 
name or resource ID range. If the resource name or ID is omitted, all resources of type 
resource-type are deleted. 


♦ Note: Of course, the delete function is valid only when the -a (append) option is 
specified in the command line. It makes no sense to delete resources while creating a 
new resource file from scratch. 


You can delete resources that have their protected bit set only if you use the -ov option. 
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Here is an example of an executable Shell command that deletes the ' ckid' resource 
from a file: 

echo "delete 'ckid';" | rez -a -o SomeTextFile 


Change—change a resource’s vital information 

You an change a resource’s vital information by using this function. Vital information 
includes the resource type, ID, name, attributes, or any combination of these at once. 


Syntax 

change resource-typel [‘(' resource-name\ id[:id]‘)’] 
to tesource-type2 ‘('id[, resource-name] [, attributes...] y ; 

Description 

Change the resource of type resource-typel from the output file with the specified 
resource name or resource ID range to a resource of type resource-type2 with the specified 
ID. You can optionally specify a resource name and resource attributes. If the resource 
name or attributes are not specified, the name and attributes are not changed. 

For example, here is a Shell command that sets the protected bit on all code resources in 
the file TestDA: 

echo "change 'CODE' to $$type ($$Id,$$Attributes | 8);" 9 
I rez -a -o TestDA 


♦ Note: The change function is only valid when the -a (append) option is specified in 
the command line. It makes no sense to change resources while creating a new 
resource file from scratch. 
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Resource—specify resource data 

Resource statements specify actual resources, based on previous type declarations. 


Syntax 

resource resource-type ‘ (’ ID[, resource-name] [, attributed')’ ‘{’ 
[ data-statement [, data-statement ]... ] 


Description 

Specifies die data for a resource of type resource-type and ID ID. The latest type 
declaration declared for resource-type is used to parse the data specification. Data- 
statements specify the actual data; data-statements appropriate to each resource type are 
defined in the next section. 

The resource definition causes an actual resource to be generated. A resource 
statement can appear anywhere in the resource description file, or even in a separate file 
specified on the command line or as an finciude file, as long as it comes after the 
relevant type declaration. 


Data statements 


The body of the data specification contains one data statement for each declaration in 
the corresponding type declaration. The base type must match the declaration. 


Base type 

string 

bitstring 

rect 

point 


Instance types 

string, cstring, pstring, wstring, char 
boolean, byte, integer, longint, bitstring 
rect 
point 


Switch data: Switch data statements are specified by using this format: 
switch-name data-body 


For example, the following could be specified for the ' ditl * type given earlier: 


CheckBox { enabled, "Check here" }, 


Array data: Array data statements have this format: 

'{’[array-element[, array-element].. 

where an array-element consists of any number of data statements separated by commas. 
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For example, the following data might be given for the • str# • resource defined earlier: 

resource 'STR#* (280) { 

{ "this", 

"is”, 

ft a ft 
® / 

"test" 

} 

}; 


Sample resource definition 

This section describes a sample resource description file for a window. (See the chapter 
“Window Manager” of Inside Macintosh for information about resources in windows.) 

Here, again, is the type declaration given above under “Sample Type Statement”: 

type ' WIND'{ 


rect; 

integer 

/* bounds */ 

docuinentProc, dBoxProc, plainDBox, /* procID 

*/ 

byte 

altDBoxProc, noGrowDocProc, 
zoomProc^S, rDocProc=16; 
invisible, visible; 

/* visible 

*/ 

fill byte; 
byte 

noGoAway, goAway; 

/* close box */ 


fill byte; 

unsigned hex longint; 

/* refCon */ 


pstring 

Untitled = "Untitled"; 

/* title */ 



); 

Here is a typical example of the window data corresponding to this declaration: 

resource 'WIND' (128,"My window",appheap,preload) { /* Status report window 

*/ 

/* Bounding rectangle */ 

/* docuinentProc etc.. */ 

/* Visible or Invisible */ 

/* GoAway or NoGoAway */ 

/* Reference value RefCon */ 
/* Title */ 

This data definition declares a resource of type ‘wind •, using whatever type declaration 
was previously specified for • wind *. The resource ID is 128; the resource name is “My 
window.” Because the resource name is represented by the Resource Manager as a 
pstring, it should not contain more than 255 characters. The resource name may contain 
any character including the null character ($00). The resource will be placed in the 
application heap when loaded, and it will be loaded when the resource file is opened. 


{40,80,120,300}, 

docuinentProc, 

Visible, 

goAway, 

0 , 

"Status Report" 
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The first statement in the window type declaration declares a bounding rectangle for the 
window: 

rect ; 

The rectangle is described by two points: the upper-left comer and the lower-right comer. 
The points of a rectangle are separated by commas like this: 

{top, left, bottom, right } 

An example of data for these coordinates is 
{40,80,120,300} 

Symbolic names: Symbolic names may be associated with particular values of a numeric 
type. Notice that a symbolic name is given for the data in the second, third, and fourth 
fields of the window declaration. For example, 

integer documentProc=0, dBoxProc=l, plainDBox=2, 
altDBoxProc=3, noGrowDocProc=4, 
zoomProc=8, rDocProc=16; /* windowType */ 

This statement specifies a signed 16-bit integer field with symbolic names associated 
with the values 0 to 4 and 16. The values 0 through 4 need not be indicated in this case; if 
no values are given, symbolic names are automatically given values starting at 0, as 
explained previously. 

In the sample window declaration, we gave the values True (1) and False (0) to two 

different byte variables. For clarity, we used those symbolic names in the window’s 

resource data; that is, 

visible, 

goAway, 

instead of their equivalents 

TRUE, 

TRUE, 

or 

l, 

l. 


Labels 


labels support some of the more complicated resources such as * nfnt 1 and color 
QuickDraw resources. Use labels within a resource type declaration to calculate offsets 
and permit accessing of data at the labels. 
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Syntax 


label ::= 
character ::= 
number ::= 
alphanum ::= 


character {alphanum}* 

I A | B | C ... 

0|1I2|3|4|5|6|7|8|9 
character | number 


Description 

Labeled statements are valid only within a resource type declaration. Labels are local to 
each type declaration. More than one label can appear on a statement. 

Labels may be used in expressions. In expressions, use only the identifier portion of the 
label (that is, everything up to, but excluding, the colon). See “Declaring Labels Within 
Arrays” later in this chapter for more information. 

The value of a label is always the offset, in bits, between the beginning of the resource and 
the position where the label occurs when mapped to the resource data. In this example, 

type 1 cool' { 
cstring; 
endOfString: 

integer = endOfString; 

}; 


resource 'cool* (8) { 

"Neato" 

} 

the integer following the cstring would contain: 

( len("Neato") [5] + null byte [1] ) * 8 [bits per byte] = 48. 


Built-in functions to access resource data 

In some cases, it is desirable to access the actual resource data that a label points to. 
Several built-in functions allow access to that data: 

■ $$BitField(label, startingPosition, numberOfBits) 

Returns the numberOfBits (maximum of 32) bitstring found startingPosition bits 
from label. 

• $$Byte(label) 

Returns tire byte found at label. 

■ $$Word(label) 

Returns the word found at label. 

■ $$Long(label) 

Returns the longword found at label. 
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For example, the resource type * str ' could be redefined without using a pstring. 
Here is the definition of ’ str ' from Types.r: 

type 'STR' { 

pstring; 

} 

Here is a redefinition of ' str 1 using labels: 
type * STR ' { 

len: byte = (stop - len) / 8 - 1; 

string[$$Byte(len)]; 
stop: ; 

}; 


Dedaring labels within arrays 

labels declared within arrays may have many values. For every element in the array, there is 
a corresponding value for each label defined within the array. Use array subscripts to 
access the individual values of these labels. The subscript values range from 1 to n where n 
is the number of elements in the array. Labels within arrays that are nested in other arrays 
require multidimensional subscripts. Each level of nesting adds another subscript. The 
rightmost subscript varies most quickly. Here is an example: 

type 'test' { 

integer = $$CountOf(arrayl); 
array arrayl { 

integer = $$CountOf(array2); 
array array2 { 
foo: integer; 

}; 

}; 

}; 

resource ’test' (128) { 

{ 

{1,2,3}, 

{4,5} 

} 

}; 


In the above example, the label foo takes on these values: 


foo[l,l] = 32 
foo[l,2] = 48 
foo[l,3] = 64 
foo[2,1] = 96 
foo[2,2] = 112 


$$Word(foo[l,l]) = 1 
$$Word(foo[1,2]) = 2 
$$Word(foo[1,3]) = 3 
$$Word(foo[2,1]) = 4 
$$Word(foo[2,2]) = 5 
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A new built-in function may be helpful in using labels within arrays: 
%$hmy]ndtx(arrayname) 

This function returns the current array index of the array arrayname. An error occurs if this 
function is used anywhere outside the scope of the array arrayname. 


Label limitations 

Keep in mind the fact that Rez and DeRez are basically one-pass compilers. This will help 
you understand some of the limitations of labels. 

♦ Note: To decompile (or “deRez”) a given type, that type must not contain any 
expressions with more than one undefined label. An undefined label is a label that 
occurs lexically after the expression. To define a label, use it in an expression before 
the label is defined. 

This example demonstrates how expressions can only have only one undefined label: 
type 'test' { 

/* In the expression below, start is defined, next is undefined.*/ 
start: integer = next - start; 

/* In the expression below, next is defined because it was used 
in a previous expression, but final is undefined.*/ 
middle: integer = final - next; 

next: integer; 
final: 

}; 

Actually, Rez can compile types that have expressions containing more than one 
undefined label, but DeRez cannot decompile those resources and simply generates data 
resource statements. 

♦ Note: The label specified in $$BitFieid (), $$Byte () , $$word ( ) , and 
$$Long () must occur lexically before the expression; otherwise, an error is 
generated. 


Using labels: two examples 

The first example shows the modified 1 ppat • declaration using the new Rez labels. 
Boldface text in the example indicates everything that is different between the 2.0 and 
3.0 versions of' ppat ' because of the use of labels. Without using labels, the whole end 
section of the resource would have to be combined into a single hex string (everything 
following the PixeiData label). Using labels, the complete • ppat * definition can be 
expressed in Rez language. 
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type 'ppat' { 

/* PixPat record */ 


integer oldPattern, 

/* Pattern type 

newPattern, 

ditherPattern; 

*/ 

unsigned longint = PixMap / 8; 

/* Offset to pixmap 

*/ 

unsigned longint = PixelData / 

8; 

/* Offset 

to data */ 



fill long; 

/* Expanded pixel image 

*/ 

fill word; 

/* Pattern valid flag 

*/ 

fill long; 

/* expanded pattern 

*/ 

hex string [8]; 

/* old-style pattern 

*/ 


/* PixMap record 

*/ 

PixMap: 



fill long; 

/* Base address 

*/ 

unsigned bitstring[l] = 1; 

/* New pixMap flag 

*/ 

unsigned bitstring[2] = 0; 

/* Must be 0 

*/ 

unsigned bitstring[13] ; 

/* Offset to next row 

*/ 

rect; 

/* Bitmap bounds 

*/ 

integer; 

/* pixMap vers number 

*/ 

integer unpacked; 

/* Packing format 

*/ 

unsigned longint; 

/* size of pixel data 

*/ 

unsigned hex longint; 

/* h. resolution (ppi) 

(fixed)*/ 

unsigned hex longint; 

/* v. resolution (ppi) 

(fixed)*/ 

integer chunky, chunkyPlanar, planar; 

/* Pixel 

storage format */ 



integer; 

/* # bits in pixel 

*/ 

integer; 

/* # components in pixel */ 

integer; 

/* # bits per field 

*/ 

unsigned longint; 

/* Offset to next plane 

*/ 

unsigned longint = ColorTable / 

8; 

/* Offset 

to color table */ 



fill long; 

/* Reserved 

*/ 

PixelData : 



hex string [(ColorTable - PixelData) / 8]; 


ColorTable: 



unsigned hex longint; 

/* ctSeed 

* / 

integer; 

/* brans Index 

*/ 

integer = $$Countof(ColorSpec) 
wide array ColorSpec { 

- 1; /* ctSize 

*/ 

integer; 

/* value 

*/ 

unsigned integer; 

1 * RGB: red 

*/ 

unsigned integer; 

/* green 

*/ 

unsigned integer; 

/* blue 

*/ 


}; 

}; 
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Here is another example of a new resource definition with the new features in bold. In this 
example, the $$BitFieid () function is used to access information stored in the 
resource, in order to calculate the size of the various data areas added at the end of the 
resource. Without labels, all data would have to be combined into one hex string. 

type 'den 1 { 


/* IconPMap (pixMap) record */ 


fill long; 

/* Base address 

*/ 

unsigned bitstring[l] = 1; 

/* New pixMap flag 

*/ 

unsigned bitstring[2] = 0; 

/* Must be 0 

*/ 

pMapRowBytes : unsigned bitstring[13]; 

/* Offset to next row 

*/ 

Bounds: rect; 

/* Bitmap bounds 

*/ 

integer; 

/* pixMap vers number 

*/ 

integer unpacked; 

/* Packing format 

*/ 

unsigned longint; 

/* Size of pixel data 

*/ 

unsigned hex longint; 

/* h. resolution (ppi) (fixed)* 

unsigned hex longint; 

/* v. resolution (ppi) (fixed)* 

integer chunky, chunkyPlanar, 

planar; /* Pixel storage 

format 

integer; 

/* # bits in pixel 

*/ 

integer; 

/* # components in pixel 

*/ 

integer; 

/* # bits per field 

*/ 

unsigned longint; 

/* Offset to next plane 

*/ 

unsigned longint; 

/* Offset to color table 

*/ 

fill long; 

/* Reserved 

*/ 


/* IconMask (bitMap) record 

fill long; 

/* Base address 

*/ 

maskRowBytes : integer; 

/* Row bytes 

*/ 

rect ; 

/* Bitmap bounds 

*/ 


/* IconBMap (bitMap) record 

fill long; 

/* Base address 

*/ 

IconBMapRowBytes : integer; 

/* Row bytes 

*/ 

rect; 

/* Bitmap bounds 

*/ 

fill long; 

/* Handle placeholder 

*/ 


CHAPTER 11 


Resource Compiler and Decompiler 329 






($$BitField(Bounds, 32, 


/* Mask data */ 

hex string [$$Word(maskRowBytes) * 

16) /‘bottom*/ 

$$BitField(Bounds, 0, 16) /*top*/)]; 

/* BitMap data */ 

hex string [$$Word(iconBMapRowBytes) * 

($$BitField(Bounds, 32, 16)/*bottom*/ 

- $$BitField(Bounds, 0, 16) /* top */)]; 


/* Color Table */ 


unsigned 

hex longint; 

/* 

ctSeed 

* / 

integer; 


/* 

transindex 

*/ 

integer 

= $$Countof(ColorSpec) 

- 

1; 

/* 

ctSize 

*/ 




wide array ColorSpec { 





integer; 

/* 

value 

*/ 


unsigned integer; 

/* 

RGB: red 

* / 


unsigned integer; 

/* 

green 

* / 


unsigned integer; 

/* 

blue 

*/ 


} ; 


/* PixelMap data */ 

hex string [$$BitField(pMapRowBytes, 0,13) * 

($$BitField(Bounds, 32,16) /* bottom */ 

- $$BitField(Bounds, 0, 16) /*top*/)]; 

}; 


Preprocessor directives 

Preprocessor directives substitute macro definitions and include files and provide 

if-then-else processing before other Rez processing takes place. 

The syntax of the preprocessor is very similar to that of the C-language preprocessor. 

Preprocessor directives must observe these rules and restrictions: 

■ Each preprocessor statement must be expressed on a single line, beginning on a new 
line and terminated by a return character. 

■ The pound sign (*) must be the first character on the line of the preprocessor 
statement (except for spaces and tabs). 

■ Identifiers (used in macro names) may be letters (A-Z, a-z), digits (0-9), or the 
underscore character ( _ ). 
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■ Identifiers may be any length. 

■ Identifiers may not start with a digit. 

■ Identifiers are not case sensitive. 


Variable definitions 

The #define and #undef directives let you assign values to identifiers: 

#define macro data 
#undef macro 

The tdefine directive causes any occurrence of the identifier macro to be replaced 
with the text data. You can extend a macro over several lines by ending the line with the 
backslash character (\), which functions as the Rez escape character. For example, 

tdefine poem "I wander \ 
thro\' each \ 
charter\'d street" 

(Quotation marks within strings must also be escaped.) 

tundef removes the previously defined identifier macro. Macro definitions can also be 
removed with the -undef option on the Rez command line. 

The following predefined macros are provided: 

Variable_Value_ 

true 1 

false 0 

r ez ^ 1 or 0 (1 if Rez is running, 0 if DeRez is running) 

derez 1 or 0 (0 if Rez is running, 1 if DeRez is running) 

Include directives 

The tinciude directive reads a text file: 

♦include file 

Include the text file file. The maximum nesting is to ten levels. For example, 

tinciude $$Shell("MPW") "MyProject:MyTypes.r" 

Note that the tinciude preprocessor directive (which includes a file) is different from 
the previously described include statement, which copies resources from another 
file. 
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If-Then-Else processing 


These directives provide conditional processing: 

#if expression 
[ #elif expression ] 

[ #else ] 

#endif 


♦ Note: Expression is defined later in this chapter. When used with the # i f and # el i f 
directives, expression may also include this expression: 
defined identifier or defined' (’ identifier 1 )' 


The following nay also be used in place of #i f: 

#ifdef macro 
♦ifndef macro 

For example, 

♦define Thai 

Resource 'STR • (199) { 

♦ifdef English 
"Hello" 

#elif defined (French) 

"Bonjour" 

#elif defined (Thai) 

"Sawati" 

#elif defined (Japanese) 
"Konnichiwa" 

#endif 

}; 


Print directive 

The #printf directive is provided to aid in debugging resource description files: 

#printf (format St ring, arguments-.) 

The format of the fprintf statement is exactly the same as the printf statement in 
the C language, with one exception: There can be no more than 20 arguments. This is the 
same restriction that applies to the s$f ormat function. The #printf directive writes 
its output to diagnostic output. Note that the #printf directive does not end with a 
semicolon. 
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For example: 

idefine Tuesday 3 

#ifdef Monday 

#printf("The day is Monday, day #%d\n", Monday) 

#elif defined(Tuesday) 

#printf("The day is Tuesday, day #%d\n", Tuesday) 
#elif defined(Wednesday) 

#printf("The day is Wednesday, day #%d\n", Wednesday) 
#elif defined(Thursday) 

#printf("The day is Thursday, day #%d\n", Thursday) 
#else 

#printf("DON'T KNOW WHAT DAY IT IS!\n") 

#endif 

The above File generates this text: 

The day is Tuesday, day *3 


Resource description syntax 

This section describes the details of the resource description syntax. For a complete 
summary definition, see Appendix D. 
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Numbers and literals 

All arithmetic is performed as 32-bit signed arithmetic. The basic constants are shown in 
Table 11-1 


■ Table 11-1 Numeric constants 


Numeric type 

Form 

Meaning 

Decimal 

nnn... 

Signed decimal constant between 4,294,967,295 and 
-2,147,483,648. 

Hex 

OXhhh... 

Signed hexadecimal constant between 0X7FFFFFFF and 

0X80000000. 


$hhh... 

Alternate form for hexadecimal constants. 

Octal 

0 ooo... 

Signed octal constant between 017777777777 and 

020000000000. 

Binary 

OB bbb... 

Signed binary constant between 
0B11111111111111111111111111111111 and 

obiooooooooooooooooooooooooooooooo. 

Literal 

1 aaaa' 

A literal may contain one to four characters. Characters 


are printable ASCII characters or escape characters.If 
there are fewer than four characters in the literal, 
then the characters to the left (high bits) are assumed to 
be $00. Characters that are not in the printable character 
set, and are not the characters \' and \ \ (which have 
special meanings), can be escaped according to the 
character escape mles. (See “Strings" later in this 
section.) 


literals and numbers are treated in the same way by the resource compiler. A literal is a 
value within single quotation marks; for instance, * * a 1 is a number with the value 65; on 
the other hand, "A" is the character A expressed as a string. Both are represented in 
memory by the bitstring 01000001. (Note, however, that "A" is not a valid number and 

• a • is not a valid string.) The following numeric expressions are all equivalent: 

'B' 

66 

' A'+l 
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Literals are padded with nulls on the left side so that the literal ' abc * is stored as shown 
in Figure 11-3. 


■ Figure 11-3 Padding of literals 


$00 

A 

B 

C 


Expressions " ~ 

An expression may consist of simply a number or literal. Expressions may also incl ude 
numeric variables, labels, and system functions. 

Table 11-2 lists the operators in order of precedence with highest precedence fust- 
groupings indicate equal precedence. Evaluation is always left to right when the priority is 
the same. Variables are defined following the table. 


■ 

Table 11-2 

Resource description expression operators 

Operator 

Meaning 

i. 

( expr) 

Parentheses can be used in the normal manner to force precedence 
in expression calculation 

2. 

-expr 

Arithmetic (two’s complement) negation of expr 


-expr 

Bitwise (one’s complement) negation of expr 


! expr 

Logical negation of expr 

3. 

exprl * expr2 

Multiplication 


exprl / expr2 

Division 


exprl % expr2 

Remainder from dividing exprl by expr2 

4. 

exprl + expr2 

Addition 


exprl - expr2 

Subtraction 

5. 

exprl« expr2 

Shift left—shift exprl left by expr2 bits 


exprl» expr2 

Shift right—shift exprl right by expr2 bits 

6. 

exprl > expr2 

Greater than 


exprl >= expr2 

Greater than or equal to 


exprl < expr2 

Less than 


exprl <= expr2 

Less than or equal to 


(Continued) 
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■ Table 11-2 (Continued) Resource description expression operators 


Operator 


Meaning 

7 . 

exprl = 

= expr2 

Equal 


exprl ! 

= expr2 

Not equal 

8. 

exprl & 

expr2 

Bitwise AND 

9. 

exprl A 

expr2 

Bitwise XOR 

10. 

exprl | 

expr2 

Bitwise OR 

11. 

i 

c# 

i 

Logical AND 

12. 

exprl | 

| expr2 

Logical OR 


The logical operators!, >, >=, <, <=, ==, !=, &&, and 11 evaluate to 1 (true) or 0 (false). 


Variables and functions 

Some resource compiler variables contain commonly used values. All Rez variables start 

with $$ followed by an alphanumeric identifier. 

The following variables and functions have string values (typical values are given in 

parentheses): 

$$Date Current date. Useful for putting timestamps into the resource 

file. The format is generated through the ROM call 
iUDatestring. (“Thursday, May 20,1987”) 

$$Format ( "formatstring ", arguments) 

Works just like the #printf directive except that $$f ormat 
returns a string rather than printing to standard output. (See the 
section “Print Directive” earlier in this chapter.) 

$$Name Name of resource from the current resource. The current 

resource is the resource being generated in a resource 
statement, being included from an include statement, being 
deleted from a delete statement, or changed in a change 
statement. 

For example, to include all * drvr' resources from one file and 
keep the same information, but also set the SYSHEAP 
attribute: 

INCLUDE "file" 'DRVR' (0:40) AS 

’DRVR ($$ID, $$Name, $$Attributes I 64) ; 


336 MPW 3.0 Reference 











The $$ Type, $$id, $$Name, and $$Attributes variables 
are undefined Outside of a change, delete, include, or 
resource statement. 

$$Resource (“filename ’, ' type •, ID I “ resourceNamd’) 

Reads the resource * type * with the ID ID or the name 
“ resourceNam? from the resource file “filename, and returns a 
string. 

$$Sheii (“ stringExpr”) Current value of the exported Shell variable {stringExpr}. Note 

that the braces must be omitted, and the double quotation 
marks must be present. 


$$Time 


$$Version 


Current time. Useful for time-stamping the resource file. The 
format is generated through the ROM call iUTimestring. 
(7:50:54 AM”) 

Version number of Rez. (“V3.0”) 


These variables and functions have numeric values: 

$$Attributes Attributes of resource from the current resource. See the 

$$Name string variable. 

$$BitField( label, startingPosition, numberOfBits) 

Returns the numberOfBits (maximum of 32) bitstring found 
startingPosition bits from label. 


$$Byte (label) 
$ $Dsy 
$$Hour 
$$ID 

$$Long (label) 

$$Minute 

$$Month 


Returns the byte found at label. 

Current day. Range 1-31. 

Current hour. Range 0-23. 

ID of resource from the current resource. See the $$Name string 
variable. 

Returns the longword found at label. 

Current minute. Range 0-59. 

Current month. Range 1-12. 

SSPackedSize (Start, RowBytes, RowCount) 

Given an offset (Start) into the current resource and two 
integers, RowBytes and RowCount, this function calls the 
ToolBox routine UnpackBits RowCount times. 
$$PackedSize( ) returns the unpacked size of the data 
found at start. Use this function only for decompiling resource 
files. An example of this function is found in Pictr. 
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$$ResourceSize Current size of resource in bytes. When decompiling, 

$$ResourceSize is the actual size of the resource being 
decompiled. When compiling, $$ResourceSize returns the 
number of bytes that have been compiled so far for the current 
resource. (See the • kchr • resource in SysTypes.r for an 
example.) 

$ $ second Current second. Range 0-59. 


$$Type 

$$Weekday 

$$Word(label) 


Type of resource from the current resource. See the $ $Name 
string variable. 

Current day of the week. Range 1-7 (that is, Sunday-Saturday). 
Returns the word found at label. 


$$Year 


Current year. 


Strings 

There are two basic types of strings: 

Text string "a..." The string can contain any printable character except ‘ " ’ and ‘Y. 

These and other characters can be created through escape 
sequences. (See Table 8-2.) The string " " is a valid string of 
length 0. 

Hex string $"hh..." Spaces and tabs inside a hexadecimal string are ignored. There 

must be an even number of hexadecimal digits. The string $ " " is 
a valid hexadecimal string of length 0. 

Any two strings (hexadecimal or text) will be concatenated if they are placed next to each 

other with only white space in between. (In this case, returns and comments are 

considered white space.) 

Figure 11-4 shows a Pascal string declared as 

pstring [10]; 

whose data definition is 

"Hello" 


■ Figure 11-4 Internal representation of a Pascal string 
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In the input file, string data is surrounded by double quotation marks ("). You can 
continue a string on the next line. A separating token (for example, a comma) or brace 
signifies the end of the string data. A side effect of string continuation is that a sequence 
of two quotation marks (" ") is simply ignored. For example, 

"Hello ""out " 

"there." 

is the same string as 

"Hello out there."; 

To place a quotation mark character within a string, precede the quotation mark with a 
backslash like this 

(\"). 

Escape characters 

The backslash character (\) is provided as an escape character to allow you to insert 
nonprintable characters in a string. For example, to include a newline character in a string, 
use the escape sequence 

\n 

Valid escape sequences are shown in Table 11-3. 


■ Table 11-3 Resource compiler escape sequences 


Escape 

sequence 

Name 

Hex 

value 

Printable 

equivalent 

\t 

Tab 

$09 

None 

\b 

Backspace 

$08 

None 

\r 

Return 

$0A 

None 

\n 

Newline 

$0D 

None 

\f 

Form feed 

$0C 

None 

\v 

Vertical tab 

$0B 

None 

\? 

Rubout 

$7F 

None 

\\ 

Backslash 

$5C 

\ 

V 

Single quotation mark 

$3A 

t 

V* 

Double quotation mark 

$22 

n 
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You can also use octal, hexadecimal, decimal, and binary escape sequences to specify 
characters that do not have predefined escape equivalents. The forms are: 


Base 

Number 

form 

Digits 

Example 

2 

\0B bbbbbbbb 

8 

XOBOIOOOOOI 

8 

\ooo 

3 

\101 

10 

\0D ddd 

3 

\0D065 

16 

\0xhh 

2 

\0X41 

16 

\$hh 

2 

\$41 


Here are some examples: 

/* 3 octal digits */ 

/* 'Ox' plus 2 hex digits */ 
/* '$' plus 2 hex digits */ 

/* 'Od' plus 3 decimal digits */ 


\077 

\0xFF 

\$F1\$F2\$F3 

\0d099 


♦ Note to Cprogrammers: An octal escape code consists of exactly three digits. For 
instance, to place an octal escape code with a value of 7 in the middle of an 
alphabetic string, write AB\007CD, not AB\7CD. 


You can use the DeRez command line option -e to print characters that would otherwise 
be escaped (characters preceded by a backslash, for example). Normally, only characters 
with values between $20 and $D8 are printed as Macintosh characters. With this option, 
however, all characters (except null, newline, tab, backspace, form-feed, vertical tab, and 
rubout) will be printed as characters, not as escape sequences. See DeRez in Part II for 
details. 
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Chapter 12 Writing an MPW Tool 


This chapter provides information specific to writing an integrated mpw 
TOOL. You’ll find the utility routines used by tools that run within the MPW Shell 
environment and how to access them. ■ 
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Overview 


This chapter provides information specific to writing an integrated MPW tool. You’ll also 
need to refer to the following: 

■ Chapter 8, “The Build Process,” for information about the mechanics of linkin g 

■ Chapter 13, “Creating a Commando Interface for Tools.” 

■ Tools Libraries in Appendix F. These contain the MPW Assembler, MPW C, and MPW 
Pascal routines for creating the rotating beach ball cursor and the Error Message File 
manager. 

■ The Graf3D Library in Appendix G. Your programs can use these routines to draw three- 
dimensional objects. 

In this chapter you’ll find the utility routines used by tools that run within the MPW Shell 
environment and how to access them. Examples of each of these routines are provided for 
MPW C, MPW Pascal, and MPW Assembly language. The MPW libraries contain four 
groups of these routines: 

■ Shell environment routines: procedures, functions, and data structures required to 
access MPW command-line parameters, Shell variables, and the standard input, 
output, and diagnostic files 

■ Shell signal-handling routines: procedures and functions that give you access to MPW 
software interrupts 

■ MPW cursor-control routines: procedures that let you control the form and action of 
the cursor. These are in Appendix F. 

■ Error message file management routines: procedures that let you access messages in 
the Macintosh system error message file. These are in Appendix F. 

These routines provide tools running within the MPW Shell environment with many 
facilities, including: 

■ parameter passing 

■ access to Shell variables 

■ a set of preopened files for text-oriented input and output 

■ I/O to windows and selections 

■ a means for returning status results 

■ signal handling (for user aborts, and so on) 

■ exit processing 
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After introducing the conventions that MPW tools should follow and the specifics of 
linking tools, each of the sections that follow explain the use of these facilities for each of 
the MPW programming languages MPW C, MPW Pascal, and MPW Assembler. 

Each section describes the environment in which the tool runs. It then lists the elements 
needed to access the libraries available to a tool. Finally, it lists the individual functions 
available to tools. Sections detailing each function are titled according to the standard C 
naming conventions and are written in this format: 

name—short description of function 

function prototytpe 

Function description: What the routine does, how to use it, arguments needed. 

MPW C 

function prototype in MPW C 

MPW Pascal 

function prototype in MPW Pascal 

Any applicable information for MPW Pascal. 

MPW Assembler 

function prototype in MPW Assembler 

Any applicable information for MPW Assembler, including the language in which the 
function is written. 


Conventions 

MPW tools adhere to a certain style that allows them to work well together in an 
integrated fashion: 

■ Tools take their inputs as command-line parameters, rather than prompting for input. 
This input style allows their execution to be automated and allows them to take 
advantage of the Shell’s command-line processing features such as variable 
substitution and filename generation. 

■ Deviations from a tool’s standard behavior are specified with command options. 
Options may be specified anywhere on the command line and their order is not 
significant. 
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■ Tools operate on a list of filename parameters, not just one, allowing the Shell’s 
filename generation feature to be exploited. 

■ When no file parameters are given, tools take their input from standard input and 
write their output to standard output. The use of standard I/O allows the piping of 
the output of one program into the input of another. For example, 

Files | Count -1 

This command sends the output of the Files command into the input of the Count 
command, yielding the number of files and directories in the current directory. 

■ Tools spin the cursor to allow switching to different applications during tool 
execution (under MultiFinder). The cursor is spun at regular intervals for cooperative 
multitasking. 

■ Most tools operate silently as they process their input. Visual feedback is provided by 
the spinning cursor. If more feedback is desired, a -p (progress) option is usually 
provided to send status and summary information to the diagnostic output. 

■ Error messages are in the form of Shell comments or are “executable” so that the error 
can be easily located. For example, the language translators report errors in the form 

File "Test.c" ; line 25 ### expected: 1 ;* got: name 

This message may be directly executed, to open the file and select the offending line. 

(See “Executable Error Messages” in Chapter 5.) 

See the “Command Prototype” section at the beginning of Part II for more information 
on MPW command language conventions. 


Status Codes 

Every tool is expected to return a status code to the Shell when it terminates. The Shell 
inspects this result—if the status code is nonzero and if the Shell variable {Exit} is nonzero 
(the default), the Shell terminates the execution of the current command file. The Shell 
also converts the result to string form and creates a Shell variable called {Status} with that 
value. The variable can then be tested with the Shell command language and action can be 
taken based on its value. 

The following conventions are used for status codes: 

0 Success 

1 Command syntax error 

2 Some error in processing 

3 System error or insufficent resources 

-9 User abort 
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♦ Note: Only the bottom 24 bits of a tool’s status code are returned to the Shell. All 
negative numbers, except for-9, are reserved for use by the Shell. See “Negative 
Status” in Chapter 5 for the meanings of negative status codes. 


You may want to return error codes other than these. In that case, you should carefully 

document the numbers and their meanings. 

MFW C Result codes are passed as the return value from your main 

function or as the parameter to the C Library exit function. 

MFW Pascal Pascal programmers must call the IntEnv procedure IEexit to 
return die status result. 

MFW Assembly The Integrated Environment routine _RTExit is available 
to assembly-language programmers. _RTExit takes the 
status code as a parameter. 


♦ Note: The returned status code will be undefined if you do not explicidy return a value 
by using the method recommended for your language. 


Restrictions 

Tools are similar to desk accessories in that they co-exist with another program (that is, 
the MPW Shell). The following sections touch on some of the considerations in enabling 
tools to co-exist with the Shell. 


Initialization 

Because tools run with the Shell, most Macintosh Toolbox initialization calls are not 
necessary and should not be called. In particular, you should not make the following calls: 
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InitFonts 

InitWindows 

InitMenus 

TEInit 

InitDialogs 

MaxApplZone 

SetApplLimit 

SetGrowZone 

InitResources 

RsrcZonelnit 

ExitToShell 

(Note that this is not an inclusive list) 

If your tool uses QuickDraw or any routine that uses QuickDraw, be sure to call the 
initGraf routine. This routine is necessary when using QuickDraw, because QuickDraw 
uses register A5-relative global variables, and tools have their own private A5 global area. 
Even a simple call to the QuickDraw function Random will not work properly unless 
InitGraf is Called. 

If your program opens any windows, make sure that it closes or disposes of those 
windows before it terminates. 

♦ Note: If your tool calls InitGraf and writes to stdout or stderr (including error 
messages), then you should call setFScaieDisabie with a parameter value of true 
after your call to InitGraf. Otherwise your text output might be improperly scaled. 


Memory Management 

The Shell and tools execute out of the same heap and share the same stack. When a tool is 
started, the Shell allocates an area in the heap for the tool’s globals and jump table, adjusts 
the global register A5 to point there, and then “calls” the tool. Any dynamic stack space 
required is allocated on the same stack, and any heap objects created go into the same 
heap. 
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■ Figure 12-1 Memory map 
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Low memory 

When a tool terminates, the Shell restores the registers to their previous values and 
deallocates the tool’s global area and any other pointers and handles in the heap that may 
have not been allocated. The tool’s resources, however, are not deallocated immediately. 
They are unlocked and made purgeable sq that the space can be used if needed. This 
practice allows for a quick restart of the tool if it is still in memory, but with no memory 
wastage should the space be needed for other purposes. 


▲ Warning Although the Shell releases memory that has been allocated by the tool, 
sometimes the Shell has insufficient information to determine the 
owner of a master pointer. When a master pointer is NIL, it cannot be 
released by the Shell and cannot be reused. 

NIL master pointers are produced as a result of calls to 
EmptyHandie, and by a number of Resource Manager actions. For 
example, a GetResource with ResLoad set to FALSE will create a 
NIL master pointer. If this is followed by a DetachResource or 
RmveResource, the handle remains as a ML pointer. It is always 
good programming practice to clean up handles after they have 
become obsolete. Use DisposHandie to get rid of such obsolete 
handles, a 
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Heap 

Because the Shell and tools share the same heap, some cooperation is necessary to ensure 
efficient use of the heap. Before a tool is started, the. Shell makes many of its heap 
objects unlocked and purgeable. The Shell’s memory-resident code is kept as low in the 
heap as possible. The tool’s code should be moved as high in the heap as possible. This is 
done automatically, if the locked bit is not set on the tool’s code resources (the default 
from the linker). When allocating heap space, tools should attempt to allocate no more 
space than is needed so that objects aren’t needlessly purged from the heap. 

When there is insufficient memory space to run a tool, you can make more space available 
in several ways. 

To obtain more memory while running MPW: 

■ Close all MPW windows. (Certain memory-resident data structures are required for 
each window.) 

■ Pipe tool output to a file, rather than to a window. 

■ Your tool may be able to borrow memory from the MultiFinder heap when running 
MultiFinder. 

To obtain more memory by relaunching MPW: 

■ If you are running MultiFinder, change the partition size for MPW in MPWs Get Info 
window. 

■ Change the hexa Shell resource as described in the next section. 

To obtain more memory by rebooting the Macintosh system: 

■ Turn off or reduce the size of the cache. (If you are running MultiFinder, you’ll need to 
reboot to change the cache size.) 

■ Remove any debuggers from the system folder. You can free up about 90K by running 
without the MacsBug debugger (that is, hold down the mouse button while booting). 

Here is the main difference between running under MultiFinder and Finder: Under 
MultiFinder, the amount of memory allocated to MPW is determined by the partition size 
(which you can change in the Info window). Under the Finder, available memory is 
affected by how much available system memory exists. 

Stack 

When the Shell starts up, it immediately grows the heap to its maximum size based on the 
maximum stack size. The default maximum dynamic stack size is 10K bytes when less than 
480K is available for the application heap; the default maximum dynamic stack size is 20K 
when more than 480K is available. Because some tools may require more stack space or 
more heap space, ' hexa • resource number 128 is available. 
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Note: Because the stack is shared between the Shell and the tool, executing tools from 
within nested scripts results in less stack space for the tool. The Shell uses about 200 
bytes of stack per nesting level. 


A Warning The MPW Shell segments might not be able to load into memory if: 

1. Your tool calls MaxMem and 

2. It allocates all available memory and 

3. You then call any Shell services (such as writing to 
an open window), a 


Building an MPW tool 


In addition to traditional Macintosh applications, the Shell provides an environment for a 
type of program called an MPW tool. When a tool is run from the Shell, it does not replace 
the Shell or erase the screen, but instead runs within the Shell environment and has access 
to the facilities provided by the Shell. The compilers, Link, Make, and so on, are all tools 
in the MPW system. 

From a programming viewpoint, tools resemble applications in many aspects of their 
behavior. Like applications, tools may have global variables and tools are linked just as 
applications are linked. The major difference between tools and applications is that tools 
do not have to initialize their environment (except for Quickdraw, if used) and tools have 
access to any of the Shell’s open windows. 

For a description of additional facilities available to an MPW tool, such as the Cursor 
Control and Error Message File Manager routines, see Appendix F. The Graf3d library is 
described in Appendix G. 


Linking a tool 

Linking an MPW tool is the same as linking an application (described in Chapter 8), 
except that the file type must be set to MPST and the creator to 'MPS' (MPSspace): 

Link -t MPST -c "MPS " ... 
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Sample tools are provided in the Examples folders for each of the MPW languages—refer 
to the sample makefiles for examples of the commands used to build a tool. Note that the 
sample tools are linked with the file Stubs.o. This file contains dummy library routines 
used to override standard library routines that aren’t used by MPW tools, thus reducing the 
tools’ code size. 


♦ Note: As a matter of convenience, tools are usually kept in the {MPWjTools folder. This 
allows you to invoke the tool by using its simple name instead of its full pathname. 
{MPWlTools is one of the directories that the Shell automatically searches when a 
command name is given with a partial pathname. The Shell variable {Commands} 
contains a comma-separated list of directories to be searched; you can easily modify 
it to include additional directories. 


See Chapter 8 for a general introduction to linking and for instructions on linking 
multilingual programs. See Chapter 10 for more detailed information on linking 


Programming for the MPW Shell 

This section explains how to access the MPW Shell by calling special MPW Pascal and MPW 
Assembler libraries. In the case of MPW C, the Shell can be accessed by using routines in 
the Standard C Library. 


Accessing the MPW Shell—MPW C 

To access the MPW 3.0 Shell environment by using MPW C, do the following: 

■ Include the necessary header files 

■ link your program with CRuntime.o, CInterface.o, and Interface.o. Also link with 
ToolLib.o if you are using the cursor control or error management routines described in 
Appendix F. You may also need to link with StdCLib.o. 

The standard C Library interface files contain most of the interfaces needed for 
programming the MPW Shell. In addition to the Standard C Library functions, MPW C 
contains: 

■ SignaLh, containing routines that give you access to MPW software interrupts 
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■ CuisorCtl.h, containing routines to control the form and action of the cursor (see 
Appendix F) 

■ ErrMgr.h, containing routines to access messages in the Macintosh system error 
message file (see Appendix F) 

The code for SignaLh is in CRuntime.o. The code for CursorCtl.h and ErrMgr.h is in 
ToolLibs.o. All interface files are in {CIncludes}. 

♦ Note: There is an example of a C tool that runs under the MPW environment in the 
folder {CExamples}. 


Accessing the MPW Shell—MPW Pascal 

To access the MPW 3.0 Shell environment by using MPW Pascal, do the following: 

■ Include the statement 

USES {$U PasLibIntf.p} PasLiblntf, {$U IntEnv.p}, IntEnv 

in your source text The uses clause and the $u Compiler directive are described in 
the MPW 3 0 Pascal Reference. 

■ Link your program with the files Runtime.o, PasLib.o, and Interface.o. If you are using 
cursor-control or error message routines, you’ll need to link with ToolLibs.o. (See 
Appendix F for information on these routines). 

MPW Pascal 3.0 includes four interface files containing facilities for programs that work 
with the MPW Shell environment. They are 

■ IntEnv.p, containing the routines and data structures required to access MPW 
command-line parameters, Shell variables, and the standard diagnostic variable 

■ SignaLp, containing routines that give you access to MPW software interrupts 

■ CursoiCtl.p, containing routines that let you control the form and action of the cursor. 
See Appendix F of this reference for detailed information on these routines. 

■ ErrMgr.p, containing routines that let you access messages in the Macintosh system 
error message file. See Appendix F of this reference for detailed information on these 
routines. 

The code for IntEnv.p and Signal.p is in the library Runtime.o. The code for CursorCtl.p 
and ErrMgr.p is in the library ToolLibs.o. 

Programmers writing tools may need to use the special facilities implemented by these 
interface files. They are all located in the directory {PInterfaces}. 
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♦ Note: There is an example of a Pascal tool that runs under the MPW environment, using 
IntEnv, in the folder {PExamples}. 


Accessing the MPW Shell:—Assembler 

To access the MPW Shell environment from MPW Assembly language, you must do the 
following: 

■ Import the names of the routines you are using. 

■ Use the correct calling conventions. 

■ Call the _RTinit function early in your program and the exit or abort procedure at 
the end of the program. 

■ Link your assembly with the library or libraries that contain the routines’ code. 

These requirements are discussed in the following sections. 

♦ Note: There is an example of an Assembly language tool that runs under the MPW 
environment in the folder {AExamples}. 


Importing the routines 

Import the names of the routines described in this appendix by using import directives. 
For the Shell environment and signal-handling routines, you can simply include the files 
IntEnv.a and SignaLa, respectively; they contain the required directives. For the cursor- 
control and error file management routines, you must write your own import directives in 
your source text. 

The Shell environment and signal-handling routines are mostly C routines; hence their 
names are case sensitive. The cursor-control and error file management routines are all 
Pascal routines. Their names are not case sensitive unless case ob j or case on is in 
effect, in which case their names must be imported in capital letters. 


Assembler calling conventions 

Each routine described in this chapter indicates whether to use Pascal or C calling 
conventions. 
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If the calling convention is C, then push the parameters on the stack from right to left. 

When the function returns, its arguments will still be on the stack and its return value will be 
in register DO. 

If the calling convention is Pascal, you must reserve space on the stack for the return 
value, if any. Then push the arguments from left to right. When the routine returns, the 
arguments will no longer be on the stack; also, the return value (if the routine was a 
function) will be on top of the stack. 

All C functions described in this chapter leave their results in register DO. All Pascal 
functions described in this chapter leave their result on the stack. 

The RTInit function 

longmt _RTInit (ptr retPC, longint * pargc, longint * pargv, longint 
longmt forPascal) 

One of the first calls in your program must be to the __RTinit function; the very last call 
should be to the exit or _exit procedure, which calls the _RTExit procedure. 

_RTinit is described in this section; _RTExit is described later under “Shell Utility 
Routines.” 

The _RTinit function allocates approximately 500 bytes of nonrelocatable space in the 
heap and calls _Datainit, the routine that initializes global data. _RTinit must be 
called before any of the other routines described in this section; if possible, it should be 
called before other code segments have been loaded. 

The_RTinit function has these parameters: 

■ retPC is the address to which program control should pass upon execution of 
_RTExit, as described under “Shell Utility Routines.” 

■ pArgc points to a long integer that _RTini t will set to the value of the Shell variable 
argc, which is discussed under “Accessing MPW Command-Line Parameters.” 

■ pArgv points to a pointer variable that _RTinit will set to the value of the Shell 
variable argv. The variable argv is discussed under “Accessing MPW Command-Line 
Parameters.” 

■ pEnvP points to a pointer variable that_RTinit will set to the vector of exported 
Shell variables. 

■ forPascal is a numeric value passed to _RTinit . Its value should be 0 if you want 
the strings pointed to by envp and argv to be in C format (terminated by a zero 
character), and one if you want them to be in Pascal format (preceded by a 
length byte). 


penvp 


354 MPW 3.0 Reference 







The _RTinit function returns a value of 1 if your program is being launched by the 
Macintosh Finder, and 0 if it is being launched by the MPW Shell. This is the value placed in 
the standAione variable, described below under “Shell Utility Routines.” 

The function _RTinit uses C calling conventions. 

For an example of the use of the _RTinit function in the code of an MPW tool, see 
Count.a. The routine init shows how to call _RTinit. The exiting routine is called 
stop; it shows how to call the very last call, exit. 

Files to link with 

The code for the Shell environment and signal-handling routines is in the library Runtime.o, 
except for the code for the iEGetEnv function, which is in PasLib.o. The code for the 
cursor-control and error file management routines is in the library ToolLibs.o. You must 
link the appropriate file or files to your object files if you use any of these routines. 


Parameters 

Parameters are passed to tools by the Shell. Every tool is passed at least one parameter: 
the name of the tool itself. This parameter is always the first parameter (technically, 
parameter 0) and is useful for error messages or other special actions. 

The text that follows the command name on the command line is first analyzed by the 
Shell for any special processing, such as filename generation or variable substitution. (See 
“How Commands Are Interpreted” in Chapter 5.) This text is then split up into individual 
words and placed in a convenient data structure for programmatic access. 

In any MPW language, there are two variables, argc and argv. 

The argument vector, argv, is a pointer to an array of string pointers. Figure 12-2 
demonstrates the argv structure. 
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■ Figure 12-2 Parameters in MPW C and MPW Pascal 
C Sample.a -a Sample Pascal Sample.p -a Sample 



The argument count, argc, contains the number of parameters including parameter 0. The 
value of argc is always greater-than or equal to one, because the first parameter is always 
the command name. For example, in Figure 12-1, the variable argc would have the value 4. 

Element 0 of argv is always the command name, as supplied by the user. When a user is 
running an MPW Shell script, it’s important that error messages include the name of the 
particular MPW program that generated the error. You can include the program name with 
code such as this (in MPW Pascal): 

progName := argv / '[0] / '; {Store program name in temp variable.) 
IF IOResult <> 0 THEN 

Writeln(diagnostic, progName, '-cannot open file', fileName); 
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Accessing MPW command-line parameters—MPW C 

In C, the main program is actually passed three parameters, named argc, the argument 
count; argv, the argument vector; and envp, the environmental pointer. The value of 
argc includes the command name (parameter 0), and is thus always one more than the 
number of parameters to the command, argv is a pointer to a zero-terminated array of 
pointers to the parameters, each of which is in C string (zero-terminated) format. (See 
Figure 12-1.) 


Accessing MPW command-line parameters—MPW Pascal 

In MPW Pascal, the parameters are accessible as the unit global variables Argc and Argv 
from the IntEnv (Integrated Environment) unit. As in C, the value of Argc is one more 
than the parameter count; Argv is a pointer to a null-terminated array of Pascal string 
pointers. 

The Integrated Environment library uses the following types and variables to allow you to 
access the information given in an MPW command line. 

The unit IntEnv in the interface file IntEnv.p declares these types and variables: 

TYPE 

IEString = STRING; 

IEStringPtr = ''IEString; 

IEStringVec = ARRAY [0..8191] OF IEStringPtr; 

IEStringVecPtr = *IEStringVec; 

VAR 

ArgC: LONGINT; 

ArgV: IEStringVecPtr; 

EnvP: IEStringVecPtr; 

Diagnostic: TEXT; 

The Argv variable is a pointer to an array of type array [ o .. Argc] of Pascal string 
pointers, dynamically allocated and initialized by the MPW Shell when a program begins 
execution. Each parameter to the program is stored as a string of type IEString and is 
pointed to by a pointer in the array. 

The code within the library routines creates strings of type IEString that are exactly the 
length of the arguments passed to them. For this reason, you cannot assign values to 
variables of type IEString— their values are passed directly from the MPW Shell. 
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Accessing MPW command-line parameters—Assembler 

The Integrated Environment routine, _RTinit, can be used to access the command 
parameters in assembly language. The addresses of the variables argv and argc are 
passed to_RTinit, which initializes them. 

The argv variable, set by _RTinit, is a pointer to an array of type array [ o.. argc ] 
of pointers, dynamically allocated and initialized by the MPW Shell when a program begins 
execution. Each command-line parameter to the program is stored as a Pascal-formatted 
or C-formatted string (depending on the value of the f orPascal parameter passed to 
_RTinit), pointed to by a pointer in the array. 


Standard I/O channels 

Before starting a tool, the Shell sets up three text I/O channels that the tool can use to 
communicate with the outside world. These are 

■ standard input 

■ standard output 

■ diagnostic output (standard error) 

By default, these channels are connected to the console (that is, the frontmost, active 
window). Program input may be typed (or selected) and entered in any window; program 
output appears immediately after the command in the same window. This input and 
output may be taken from or directed to other files by specifying I/O redirection (<, >, 
>> . , 2, or 22) on the command line. When the Shell encounters the I/O 

redirection notation, it opens or creates the necessary files, removes the redirection 
notation from the command line so that it doesn’t appear in the program’s parameter list, 
and then arranges for the open files to be passed to the program. When the tool finishes, 
the Shell flushes any buffered output and closes the files. 


I/O buffering 

When using I/O routines provided by the language libraries, varying degrees of buffering 
are expected to occur on the standard I/O channels: 
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■ Input from the console is buffered until the Enter key is pressed. If there is a selection 
when Enter is pressed, the selected text is used to satisfy the console read request; 
otherwise, the entire line that contains the insertion point is given to the reader. 

♦ Note: The MPW method of reading input creates a difficulty for interactive 
tools that write prompting text and pause to read a response entered on 
the same line: The tool will receive the prompt back as part of the line read, 
unless there was a selection when Enter was pressed. 

■ When input is taken from a file, the I/O package will, by default, read the data from 
the disk in IK blocks. 

■ Text written to standard output is also buffered IK at a time before being sent to a 
file or to the console. (As a convenience, when a read request is issued to the console, 
all interactive output buffers are flushed so that any prompting text will appear before 
the program pauses waiting for input.) 

■ Text written to the diagnostic channel is buffered one line at a time, so that error 
messages and progress information appear in a timely manner while the program is 
executing. 

Note that this buffering can cause apparently anomalous behavior: In particular, if both 
standard output and diagnostic output are directed to the console, the order of the 
output on the screen may not match the order in which the data was written.This change in 
order may result because the separate buffers are flushed at different times, as illustrated 
in Figure 12-3. You can circumvent this problem by flushing standard output before writing 
to diagnostic output. 

♦ Note: Figure 12-3 shows the output conventions in C and Pascal. Assembly-language 
programmers must do their own buffering, or call C or Pascal routines. 
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■ Figure 12-3 I/O buffering 



C The standard I/O files are available for reading or writing in C, via the 

file descriptors 0,1, and 2, or the StdIO stream descriptors stdin, 
stdout, stderr. These descriptors are fully documented in the 
MPW S O C Reference. 

Pascal In Pascal, the program parameters input and output correspond to 
the standard input and output channels. A text file variable called 
diagnostic, which is connected to the standard diagnostic channel, 
is available from the IntEnv unit. Most tools written in Pascal can use 
the standard Pascal input and output functions with the text files 
input, output, or Diagnostic. The use of these parameters is 
documented in detail in the MPW S O Pascal Reference. 


I/O to windows and selections 

The MPW environment also provides to tools the ability to read and write to windows or 
to selections within windows. No special programming is required to use this feature. The 
MPW Shell monitors file system calls, and intercepts those that refer to a file that is 
currently open as a window. These calls are redirected automatically to the window rather 
than the file. (Thus, any modifications to the file do not become permanent until the 
window is saved.) 
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Accessing selections within windows is equally transparent to programs. All that is required 
is that the filename contain the selection suffix (.§). Reading from a selection is the same 
as reading from a file, and the beginning and end of the selection are treated as the 
bounds of the file. However, writing to a selection replaces the selection and has the 
interesting property that the data written is inserted into the file, rather than overwriting 
the data that follows. 

Because window and selection I/O is handled automatically by the MPW Shell, tools 
should simply assume that they are always dealing with files. 


Error information 

All Shell I/O routines report errors by setting the value of the integer variable errno. In 
addition, the routines open, close, read, write, and iocti set the variable 
MacosErr. The error values are shown in Table 12-1. 

MPW C The variables errno and MacosErr are global variables. 

MPW Pascal Results are reported with i oresult, which looks at both errno and 

MacOSErr. If IOresult is positive, it holds errno. If IOresult 
is negative, it holds MacosErr. 

MPW Assembly import the variables errno (a long) and MacosErr (a word). You 
can import these variables with the IntEnv.a interface file. 

The variable errno is an integer. Its behavior is described in the MPW3.0 CReference. 
The values of errno are typically small positive integers. Zero means that there is no 
error. However, libraries do not set errno to zero on successful calls. 

MacosErr is a short that holds the error result from Macintosh toolbox calls made by the 
libraries (such as the result of a file system call made by the iocti function). MacosErr 
holds zero if there is no error; if it holds a negative number, that means there is an error. 

See Inside Macintosh for details on error numbers. 
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■ Table 12-1 Shell I/O errors 


Value Identifier Message 


Explanation 


2 


3 


5 


6 


7 

9 


12 

13 


ENOENT 

No such file or directory. 

This error occurs when a file whose 
filename is specified does not exist 
or when one of the directories in a 
pathname does not exist. 

ENORSRC 

Resource not found 

A required resource was not found. 
This error applies to faeces s alls 
that return tab, font, or print record 
information. 

EIO 

I/O error 

Some physial I/O error has 
occurred. This error may in some 
cases be signaled on a all following 
the one to which it actually applies. 

ENXIO 

No such device or address 

I/O on a special file refers to a 
subdevice that does not exist, or 
the I/O is beyond the limits of the 
device. This error may also occur 
when, for example, no disk is 
present in a drive. 

E2BIG 

Insufficient space for 
return argument 

The data to be returned 
is too largefor 

the space alloated to receive it. 

EBADF 

Bad file number 

Either a file descriptor does not 
refer to an open file, or a read (or 
write) request is made to a file that 
is open only for writing (or reading). 

ENOMEM 

Not enough space 

The system ran out of memory while 
the library call was executing. 

EACCES 

Permission denied 

An attempt was made to access a 
file in a way forbidden by the 
protection system. 


(Continued) 
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■ Table 12-1 (Continued) Shell I/O errors 


Value 

Identifier 

Message 

Explanation 

17 

EEXIST 

File exists 

An existing file was mentioned in an 
inappropriate context. 

19 

ENODEV 

No such device 

An attempt was made to apply an 
inappropriate system call to a 
device; for example, to read a 
write-only device. 

20 

ENOTDIR 

Not a directory 

An object that is not a directory 
was specified where a directory is 
required; for example, in a path 
prefix. 

21 

EISDIR 

Is a directory 

An attempt was made to write on a 
directory. 

22 

EINVAL 

Invalid parameter 

Some invalid parameter was 
provided to a library function. 

23 

ENFILE 

File table overflow 

The system’s table of open files is 
full, so temporarily a call to open 
cannot be accepted. 

24 

EMFILE 

Too many open files 

The system cannot allocate memory 
to record another open file. 

28 

ENOSPC 

No space left on device 

During a write to an ordinary file, 
there is no free space left on the 
device. 

29 

ESPIPE 

Illegal seek 

An lseek was issued incorrecdy. 

30 

EROFS 

Read-only file system 

An attempt to modify a file or 
directory was made on a device 
mounted for read-only access. 

31 

EMLINK 

Too many links 

An attempt to delete an open file 
was made. 
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Shell I/O routines—MPW C 


The MPW C input and output routines are part of the comprehensive Standard C Library. 
The Standard C Library is a collection of basic routines that let you read and write files, 
examine and manipulate strings, perform data conversion, acquire and release memory, 
and perform mathematical operations. You may use any of the Standard C Library routines 
or low-level routines individually described later in this chapter. For more information, see 
the MPW3-0 C Reference. 

stdio—standard buffered input/output package 

The Standard I/O package constitutes an efficient user-level I/O buffering scheme. The 
inline macros getc and putc handle characters quickly. 

The following macros and higher-level routines all use getc and putc: 


getchar 

putchar 

fgetc 

fgets 

fprintf 

fputc 

fputs 

f read 

fscanf 

fwrite 

gets 

getw 

printf 

puts 

putw 

scanf 


Calls to these macros and functions can be freely intermixed. 

The constants and the following functions are implemented as macros: 

getc getchar putc putchar 

feof ferror clearerr fileno 

Avoid redeclaration of these names. 

Any program that uses the Standard I/O package must include the <StdIO.h> header file 
of macro definitions. The functions, macros, and constants used in the Standard I/O 
package are declared in the header file and need no further declaration. 

A stream is a file with associated buffering and is declared to be a pointer to a fi le 
variable. Functions f open, f reopen, and f dopen return this pointer. The information in 
the file variable includes 

■ the file access—read or write 

■ the file descriptor as returned by open, creat, dup, or f cnti 

■ the buffer size and location 

■ the buffer style (unbuffered, line buffered, or file buffered) 
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Output streams, with the exception of the standard error stream stderr, are by default 
file buffered if the output refers to a file. File stderr is by default line buffered. When an 
output stream is unbuffered, it is queued for writing on the destination file or window as 
soon as written; when it is file buffered, many characters are saved up and written as a 
block; when it is line buffered, each line of output is queued for writing as soon as the line 
is completed (that is, as soon as a newline character is written). Function setvbuf may 
be used to change the stream’s buffering strategy. 

Normally, there are three open streams with constant pointers declared in the <StdIO.h> 
header file and associated with the standard open files: 


■ Table 12-2 Standard files 


FILE variable 

Fiklcs 

Description 

Buffer style 

stdin 

0 

standard input file 

file buffered 

stdout 

1 

standard output file 

file buffered 

stderr 

2 

standard error file 

line buffered 


Buffer initialization: The file variable returned by f open, f reopen, or fdopen has an 
initial buffer size of 0 and a null buffer pointer. The buffer size is set and the buffer 
allocated by a call to setbuf, setvbuf, or the first I/O operation on the stream, 
whichever comes first. Buffer initialization is done using the following algorithm: 

1. If _ionbf (no buffering) was set by a call to setvbuf, initialization steps 2 and 3 are 
skipped. The buffer size remains 0 and the buffer pointer remains null. 

2. Checks the access-mode word for _iolbf (line buffering). This bit is usually set only 
in the predefined file stderr, but a call to setvbuf can set it for any file. If line 
buffering is set, the buffer size is set to lbufsiz (100). If line buffering is not set, 
iocti is called with an fiobufsize request and the buffer size is set to the returned 
value or to bufsiz (1024) if no value is returned. 

3. If the buffer pointer is null, a request is made for a buffer whose size was 
determined in step 2; the buffer pointer is set to point to the newly allocated buffer. 

If the requested size cannot be allocated, attempts are made to allocate bufsiz or 
lbufsiz if these are smaller than the requested size. If all requests fail, the buffer 
pointer remains null and the _ionbf (no buffering) bit is set. 

4. Function iocti is called with an fiointeractive request; if it returns true, the 
_iosync bit is set in the access-mode word. This is done for all file variables, 
regardless of their buffering style and size. (The _iosync bit is described in the nex t 
section.) 
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The setvbuf function lets you specify values for buffer size, buffer pointer, and access- 
mode word other than the default values of 0, null, and 0, respectively. The setvbuf 
function must be called before the first I/O operation occurs, so that the buffer 
initialization procedure described above receives the values you specify instead of the 
default values. 

Buffered I/O: On each write request, the bytes are transferred to the buffer and an 
internal counter is set to account for the number of bytes in the buffer. If _iolbf is set 
and a newline character is encountered while transferring bytes to the buffer, the buffer is 
flushed (written immediately) and the transfer continues at the beginning of the buffer. 
This continues until the write-request count is satisfied or a write error occurs. 

On each read request, the _iosync bit in the access-mode word is checked. If _iosync 
is on, all current file variables that have _iosync on and are open for writing are 
flushed. In other words, a read from an interactive file variable flushes all interactive 
output files before reading. This ensures that any prompts, I/O in a window, or other 
visual feedback is displayed before the read is initiated. Then if the internal counter is 0, 
an entire buffer is read into memory if possible. (For the console device, less than a 
buffer’s worth is likely to be read.) The bytes required to satisfy the read request are 
transferred, going back to the device for more if necessary, and an internal pointer is 
advanced if any bytes remain unread. 

When the Standard I/O package is used, Standard I/O cleanup is performed just before 
termination of the application. Any normal return including a call to exit causes Standard 
I/O cleanup, which consists of a all to f close for every open file stream. 


A Warning Do not use a file descriptor (0,1, or 2) where a FILE variable (stdin, 
stdout, or stderr) is required. File <StdIO.h> includes definitions 
other than those described above, but their use is not recommended. 
Invalid stream pointers ause serious errors, possibly including 
program termination. Individual function descriptions describe the 
possible error conditions. ▲ 


An integer constant eof (-1) is returned upon end of file or error by most integer 
functions that deal with streams. See the descriptions of the individual functions for 
details. 


You may also refer to these Standard C library routines: 


close 
fopen 
gets 
printf 
scant 


exit 

fread 

Iseek 

putc 

setbuf 


fclose 
fseek 
onexit 
puts 
ungetc 


terror 

getc 

open 

read 

write 
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Shell I/O routines—MPW Pascal 

The Integrated Environment library includes four general I/O routines that you can use in 
conjunction with the standard Pascal I/O routing from MPW Pascal programs that run 
within the MPW environment. These functions are listed, where available, in the next 
section. 


Shell I/O routines—Assembler 

Eight general I/O routines are available for use with MPW Assembler programs that run 
within the MPW environment 


Shell I/O routines 

In the sections that follow, each I/O routine is individually described, along with the 
appropriate calls in MPW C, MPW Pascal, and MPW Assembly language. 


open—open for reading or writing 

int open(char *filename / int mode) 

The Shell routine open opens the file, window, or selection named by filename for both 
reading and/or writing. The parameter mode sets the file-status flags, and specifies file 
creation, truncation, and/or exclusive access. 
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To construct mode, first select one of the following access modes: 

■ o_rdonly Open for reading only. 

■ o_wronly Open for writing only. 

■ o_hdwr Open for reading and writing. 

Then optionally add one or more of these modifiers: 

■ o_append The file pointer is set to the end of the file before each write. 

■ o_creat If the file does not exist, it is created. 

m ojtrunc If the file exists, its length is truncated to 0; the mode is 

unchanged. 

■ o_rsrc The file’s resource fork is opened. (Normally, the data fork is 

opened.) 

The following setting is valid only if o_creat is also specified: 

■ o_excl Function open fails if the file exists. 

Upon successful completion, a nonnegative integer (the file descriptor) is returned. The 
file pointer used to marie the current position within the file is set to the beginning of the 
file. 


The named file is opened unless one or more of the following are true: 

■ o_creat is not set and the named file does not exist, [enoent] 

■ More than about 30 file descriptors are currendy open. The actual limit varies 
according to runtime conditions, [emfile] 

■ o CREATando excl are set and the named file exists, [eexist] 


MFWC 

int open(char ♦filename, int mode) 

MPW Pascal 

PROCEDURE IEopen(VAR fvar: univ PascalFile; filename: string; mode 
longint); 

After iEopen executes successfully, fvar contains a pointer to the beginning of the file 
named by filename. 

Normally, MPW Pascal tools will use the built-in calls Reset, Rewrite, or open. The 
Procedure IEopen provides additional options with the mode parameter. After using 
iEopen, the tool should then use the built-in MPW Pascal calls Read, write, and close 
using the fvar variable. 


368 MPW 3.0 Reference 



MPW Assembler 

longint open(char *filename, longint mode) 

Use the C routine open . After open executes successfully, DO contains an integer file 
descriptor (a nonnegative integer), with the file pointer set to the beginning of the file. 

File descriptors for input, output, and the diagnostic output are predeclared in the 
include file IntEnv.a, as shown in Table 12-3. 


■ Table 12-3 Predeclared file descriptors 


Value 

Identifier 

File 

0 

InputFD 

Standard input 

i 

OutputFD 

Standard output 

2 

DiagnosticFD 

Diagnostic output 


If there is an error, DO will contain -1 and errno will be set to indicate the error. 


dose—dose a file descriptor 

int close(int fd) 

The close function closes the file associated with the file descriptor fd. (The file 
descriptor is obtained from an open call.) 

Function close fails if fd is not a valid open file descriptor. 

Upon successful completion, a value of 0 is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 

MPW C 

int close(int fd) 

(File descriptor f d may also be obtained from a creat, dup, or f cnti call.) 

MPW Pascal 

To close a file opened with iEopen, use the MPW Pascal built-in procedure close. 

MPW Assembler 

longint close(longint fd) 

Use the C function close. If successful, close sets DO to 0. 
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read—read from a file 

int read(int fd, char *buf, unsigned nbyte) 

On devices capable of seeking, read starts reading at the current position of the file 
pointer associated with f d. Nonseeking devices always read from the current position. 
The value of a file pointer associated with such a file is undefined. 

Upon return from read, the file pointer is incremented by the number of bytes actually 
read. 

File descriptor f d is obtained from a call to open. Function read transfers up to nbyte 
bytes from the file associated with f d into the buffer pointed to by buf. 

Upon successful completion, read returns the number of bytes actually read and placed in 
the buffer; this number may be less than nbyte if the file is associated with a window or if 
the number of bytes left in the file is less than nbyte bytes. 

File descriptor 0 is opened by the MPW Shell as standard input. 

A value of 0 is returned when an end of file has been reached, or -1 if a read error occurred. 
Upon successful completion, a nonnegative integer is returned indicating the number of 
bytes actually read. Otherwise, -1 is returned and errno is set to indicate the error. 

Function read fails if f d is not a valid file descriptor open for reading. 

MPW C 

int read(int fd, char *buf f unsigned nbyte) 

(File descriptor f d may also be obtained from a creat, dup, or f cnti call.) 

MPW Pascal 

To read from a file opened with iEOpen, use the MPW Pascal built-in procedure Read. 

MPW Assembler 

longint read(longint fd, char *buf, unsigned longint nbyte) 

Use the C routine read. If successful, read leaves the number of bytes actually read in DO 
(which may be less than nbyte, if the end-of-file was encountered); otherwise it sets DO to 
-1 and sets the value of errno. 
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write—write to a file 

int write(int fd, char *buf, unsigned nbyte) 

The function write attempts to write nbyte bytes from the buffer pointed to by buf 
to the file associated with the f d. (File descriptor fd is obtained from an open.) Internal 
limitations may cause write to write fewer bytes than requested; the number of bytes 
actually written is indicated by the return value. Several calls to write may therefore be 
necessary to write out the contents of buf. 

On devices capable of seeking, the actual writing of data proceeds from the position in 
the file indicated by the file pointer. Upon return from write, the file pointer is 
incremented by the number of bytes actually written. On nonseeking devices, writing 
starts at the current position. The value of a file pointer associated with such a device is 
undefined. 

If the o_append file status flag set in open is on, the file pointer is set to end of file 
before each write. 

The file pointer remains unchanged and write fails if f d is not a valid file descriptor 
open for writing. 

If you try to write more bytes than there is room for on the device, write writes as many 
bytes as possible. For example, if nbyte is 512 and there is room for 20 bytes more on the 
device, write writes 20 bytes and returns a value of 20. The next attempt to write a 
nonzero number of bytes will return an error. 

File descriptor 1 is standard output; file descriptor 2 is standard error. 

Upon successful completion, the number of bytes actually written is returned. Otherwise, 

-1 is returned and errno is set to indicate the error. 

MPWC 

int write (int fd f char *buf f unsigned, nbyte) 

(File descriptor f d may also be obtained from a creat, dup, or f cnti call.) 

MPW Pascal 

To write to a file opened with iEopen, use the MPW Pascal built-in procedure write. 

MPW Assembler 

longint write(longint fd, char *buf, unsigned longint nbyte) 

Use the C loutine write. 
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lseek—move read/write file pointer 

int lseek(int fd, int offset, int whence) 

The function lseek moves the read/write file pointer in the file associated with fd, 
according to the following value of whence and offset: 

■ If whence is 0, the pointer is set to offset bytes. 

■ If whence is 1, the pointer is set to its current location plus offset. 

■ If whence is 2, the pointer is set to the size of the file plus offset. 

■ If whence is 1 or 2, the value of offset may be negative. 

Upon successful completion, the file pointer value, as measured in bytes from the 
beginning of the file, is returned. 

The file pointer remains unchanged and lseek fails if one or more of the following are 
true: 

■ File descriptor f d is not open, [ebadf] 

■ Parameter whence is not 0,1, or 2. [einval] 

■ The resulting file pointer would point past end of file, [espipe] 

■ The resulting file pointer would point before beginning of file, [einval] 

Some devices are incapable of seeking. The value of the file pointer associated with such 
a device is undefined. Upon successful completion, a nonnegative long integer indicating 
the file-pointer value is returned. Otherwise, a value of -1 is returned and errno is set to 
indicate the error. 

A Warning Function lseek has no effect on a file opened with the o_append 
flag because the next write to the file always repositions the file 
pointer to the end before writing. ▲ 

MFWC 

int lseek(int fd, int offset, int whence) 

MFW Pascal 

FUNCTION IElseek(VAR fvar: UNIV PascalFile; offset: LONGINT; whence: 
LONGINT): LONGINT; 

Do not use iELseek with a structured file. 
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MFW Assembler 

longint lseek(longint fd, longint offset, longint whence) 
Use the C function lseek. 


fcntl—file control 

int fcntl (int fd, unsigned int cmd, int arg) 

Function fcntl duplicates a File descriptor. A file remains open until all its file 
descriptors are closed. Parameter f d is an open file descriptor obtained from an open 
call. Parameter cmd takes the value f_dupfd, which tells fcntl to return the lowest 
numbered available file descriptor greater than or equal to arg. 

Normally arg is greater than or equal to 3, in order to avoid obtaining the standard file 
descriptors 0,1, and 2. Function fcntl returns a new file descriptor that points to the 
same open file as f d. The new file descriptor has the same access mode (read, write, or 
read/write) and file pointer as f d. Any I/O operation changes the file pointer for all file 
descriptors that share it. 

Function fcntl fails if one or more of the following are true: 

■ Parameter f d is not a valid open file descriptor, [ebadf] 

■ Parameter arg is negative or greater than the highest allowable file descriptor. 
[einval] 

Upon successful completion, the value returned is a new file descriptor. Otherwise, a value 
of— 1 is returned and errno is set to indicate the error. 

♦ Note: The f_getfd, f_setfd, f_getfl, and f_setfl commands of fcntl 
are not supported on the Macintosh. 


MPWC 

int fcntl(int fd, unsigned int cmd, int arg) 

MPW Pascal 

The function fcntl is not supported in MPW Pascal. 

MPW Assembler 

longint fcntl(longint fd, unsigned longint cmd, longint arg) 

Use the C routine fcntl. 
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IOCtl—communicate with device handler 

The function iocti communicates with a file’s device handler by sending control 
information and/or requesting status information. 

The cmd parameter specifies one of the following device-specific operations: 


FIOINTERACTIVE 

Return a value of 0 if the device is interactive, -1 otherwise. 

Ignore arg. 

FIOBUFSIZE 

Return the default buffer size for the device. The buffer size is 
expressed in bytes and is returned as a longint value pointed to 
by arg. If the device has no default buffer size, iocti returns a 
value of —1; it returns 0 otherwise. 

FIOFNAME 

Store the filename associated with f d in a character array 255 
characters in size, pointed to by arg. IEioctl returns a value of 
-1 if the filename length exceeds 255 characters, 0 otherwise. 

FIOREFNUM 

Return the Macintosh file reference number associated with f d. 

The reference number is returned as an integer value pointed to 
by arg. iocti returns a value of-1 if the file associated with f d 
is not open on a Macintosh file (such as the console device), 0 
otherwise. 

FIOSETEOF 

Set the logical end of the file associated with f d to the value of 
arg, which becomes the new size of the file in bytes. This 
command can be used to reduce or increase the size of an open 
file. The current file pointer is not affected unless the file size is 
set to a value lower than the position to which it points. 

TIOFLUSH 

Discard unread terminal input This parameter value is used only 
for the console device and other terminal devices, iocti returns 
a value of-1 if the file associated with fd is not a terminal 
device, 0 otherwise. Parameter arg is ignored. 

MPW C 



int iocti(int fd, unsigned int cmd, long *arg) 

The cmd constants are in iocti. h. 

MPW Pascal 

FUNCTION IEioctl(VAR fvar: UNIV PascalFile; cmd: LONGINT; arg: UNIV 
LONGINT): LONGINT; 

Tlie cmd constants are defined in intEnv unit 
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MPW Assembler 


longint ioctl(longint fd, unsigned longint cmd, longint *arg) 
Use the C function ioctl. The cmd constants are defined in intEnv.a. 


Shell utility routines 

These utilities are useful when writing an MPW tool. The utility routines provide methods 
to: 

■ determine whether a program is running under the MPW Shell (standAi one) 

■ to access the values of MPW Shell variables (getenv) 

■ to specify exit handlers (atexit) 

■ to terminate the current application (exit) 

■ to access information about MPW Shell documents (f access) 


StandAlone—check whether running under the MPW Shell 

The standard libraries provide a method to tell whether a program is r unnin g under the 
MPW Shell. 

MPW C 

The global variable StandAlone is an int. If StandAlone is zero, the program is running 
under the MPW Shell. 

MPW Pascal 

FUNCTION IEStandalone: BOOLEAN; 

The IEStandalone function returns a result of type boolean. The result is false if the 
program is running under MPW, true if it is not 

MPW Assembler 

Import the longint variable StandAlone (in the Interface file IntEnv.a). If 
StandAlone is non-zero, the program is running under the MPW Shell. 
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getenv—access exported MPW Shell variables 

char *getenv(char *varname) 

The MPW Shell maintains a set of state variables that can be made available to tools with 
the Export command. (See “Variables” in Chapter 5 for the list of standard exported Shell 
variables.) Whenever you run a tool, the Shell makes a copy of the names and string values 
of all exported variables and passes this list to the program. The tool can then determine 
the value of a variable by one of two methods: 

■ doing a linear search of the list of variables until the desired variable name is found 

■ using the getenv function 

Because only a copy is passed, a tool cannot alter the Shell’s value of a variable. 

Function getenv searches the environment for a Shell variable with the name specified by 
vamame and returns a pointer to the character string containing its value. The null pointer 
is returned if the Shell variable is not defined or has not been exported. The Shell-variable 
name search is case-insensitive. 

For standalone applications, which do not run under the MPW Shell, getenv always 
returns the null pointer. 

MPW C 

char *getenv (char *varnairte) 

The environment can also be accessed by means of a parameter to the C main-entry-point 
function main if the main procedure is declared as 
main(argc, argv, envp) 

The envp array represents the set of MPW Shell variables that have been made available to 
tools by means of the MPW Export command. The ith envp entry has the form 

envp[i] = "varname\0varvalue\0"; 

The last envp entry is the null pointer. 

If you use envp to search the environment, be sure to use case-insensitive string 
comparisons. 

MPW Pascal 

FUNCTION IEgetenv(envName: STRING; VAR envValue: UNIV IEString): 
BOOLEAN; 






576 MPW 3.0 Reference 









iEGetEnv returns true if it is successful in finding the value of a variable that is defined 
and exported in the MPW Shell environment. The parameter envName is a Pascal string 
naming an exported Shell variable, with uppercase and lowercase not distinguished. The 
parameter envvaiue is returned with the value of the Shell variable. IEGetEnv returns 
false if it cannot find the variable. 

Pascal programmers are also provided with another IntEnv unit global variable, called 
EnvP. The variable Envp points to a list of variable name and value pairs. The structure 
used is the same as that for C, except that the vamame is in Pascal string format. 

♦ Note: VarValue is in c string format, that is, null-terminated with no length-byte. 
Please refer to Figure 12-4. 


■ Figure 124 Format of envp array for MPW C and MPW Pascal 


MPW C 


MPW Pascal 



MPW Assembler 

char *getenv(char *varname) 

Function IEgetenv(envName: string; VAR envValue: univ IEString): 
boolean; 

Use getenv if the value of the f orPascai parameter in the _RTinit call was 0; 
Otherwise use IEGetEnv. 


CHAPTER 12 Writing an MPW Tool 377 



































































The Integrated Environment routine, _RTinit, can also be used to access Shell variables 
in assembly language. The address of envp is passed to _RTinit, which initializes it. You 
can choose Pascal or C strings (by setting f orPascal to the appropriate value in the call 
to RTInit). 


A Warning Functions getenv and iEGetEnv return a pointer to the place in 
memory where a copy of the MPW Shell variable resides. Do not 
modify the value of a Shell variable in such a way as to increase its 
length. ▲ 


atexit—install a function to be executed at program termination 

int atexit(void (*func)(void)) 

Normal program termination closes and flushes open files and releases program memory. If 
you want additional exit processing, you can use atexit to insert a routine that is 
executed just before normal termination. The parameter f unc is a pointer to such a 
routine. Up to 32 exit procedures are permitted (not including the one used by the 
Standard I/O Package to flush all the buffers). The routines specified will be executed in 
the reverse order of their installation. The routines will be called with no parameters. 

MPW C 

int atexit(void (*func)(void)) 

The routine atexit returns a zero value if the installation succeeds. 

MPW Pascal 

PROCEDURE IEatexit(exitProc: UNIV LONGINT); C; 

The exit routines cannot be nested procedures. 

MPW Assembler 

int atexit(void (*func) (void)) 

Use the MPW C atexit routine. 

A Warning If a function is installed more than once, it will be executed as many 
times as it was installed. ▲ 
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exit—terminate the current application 

void exit(int status) 
void abort() 

The functions exit and abort close open file descriptors and terminate the application 
or tool. Here is the order in which exit performs its duties: 

1. It executes all exit procedures in reverse order of their installation by atexit, 
followed by the exit procedures for the Standard I/O package if Standard VO 
routines were used. All buffered files are flushed and closed. 

2. It closes all open files that were opened with open. 

3* If the program is a tool running under the MPW Shell, exit places the lower three bytes 
of status into the Shell’s status variable and returns control to the MPW Shell. 

4. If the program is an application, exit terminates the application. 

There is no return from exit or abort. 

The functions exit and abort do not close files your tool opened with calls to the I/O 
routines documented in Inside Macintosh. However, the MPW Shell closes them after the 
tool returns. 

Status should be 0 for normal execution or a small positive value for errors. (See the 
section “Status Codes” at the beginning of this chapter.) 

The function exit takes a value that will be returned to the caller; abort does not 

MPW C 

void exit(int status) 
void abort() 

Notice that in MPW C the main program is a function that returns an integer. The return 
value of main is interpreted by the MPW Shell as the program status. Main programs that 
return to the Shell without setting status to an integer value will return a random status. 

MPW Pascal 

PROCEDURE IEexit(status: LONGINT); C; 

PROCEDURE IEabort(); C; 

MPW Assembler 

void exit(longint status) 
void abort() 

Both the exit and abort procedures terminate a program running under the MPW Shell 
by calling _RTExit. The action of_RTExit is described below. 

_RTExit(longint status); 
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The _RTExit procedure must be the last executed routine in a tool running under the 
MPW Shell. It calls any routines installed by the atexit procedure (described above) and 
then returns control to the address specified by the ret pc parameter in the original 
_RTInit call. 

Programs normally call the exit or abort procedure, described above. 


faccess—named file access and control 

int faccess(char ‘filename, unsigned int cmd, long *arg) 

The function faccess provides access to control and status information for named files. 

The parameter cmd must be set to one of the constants in the following list to indicate 
what operation is to be performed on the file. As noted in the list, some calls to faccess 
also require the arg parameter, usually as a long or as a pointer to a long. 

The following commands are available to all programs: 

f_delete Deletes the named file, or returns an error if the file is open or in a window. 
Arg is ignored. 

f_rename Renames the named file. Arg is a pointer to a string containing the new 
name. 


The following commands are available to programs running under the MPW Shell. All of 
these calls can be used on open or closed files. 


F GTABINFO 


F STABINFO 


F GFONTINFO 


Returns the tab setting for an MPW text file named by filename. 
Arg is a pointer to a long integer. The long integer’s value is the tab 
setting expressed as the number of spaces in the text file’s font. 

Sets the tab setting for an MPW text file named by filename. 
Arg is a long integer representing the tab setting expressed as the 
number of spaces in its font 

Returns the font and font size of an MPW text file named by 
filename. Arg is a pointer to a long integer. The font number is 
stored in the upper word of the long integer; the font size is stored 
in the lower word. 
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F SFONTINFO 


F GPRINTREC 


F SPRINTREC 


F GSELINFO 


F SSELINFO 


Sets the font and font size of an MPW text file named by 
filename. Arg is a long integer. The font number is read from the 
upper word of the long integer; the font size is read from the lower 
word. 

Gets a print record TPrint for the MPW text file filename. 
Arg is a handle to the print record. Before calling f access with 
this cmd value, the Macintosh Printing Manager must be initialized 
and the print record handle THPrint must be allocated. 

Sets a print record for the MPW text file filename. Arg is a 
handle to the print record. Before calling f access with this cmd 
value, the Macintosh Printing Manager must be initialized and the 
print record handle THPrint must be allocated. 

Gets the selection information for the MPW text file filename. 
Arg is a pointer to a selection record. 

A selection record is a C structure (or Pascal record) in this form: 

struct SelectionRecord { 
long startingPos; 
long endingPos; 
long dispayTop 

}; 

The startingPos is the starting position of the selection, the 
endingPos is the ending position of the selection, and displayTop 
is the position of the first character at the top of the window. All 
three positions are offsets from the beginning of the file, with the 
first position in the file being 0. 

Sets the selection information for the MPW text file filename. 
Arg is a pointer to a selection record described above. The display 
will start on the line that contains the character displayTop. 
DisplayTop does not have to be the first character in a line. The 
window will not automatically scroll horizontally to display the 
actual character specified. It is invalid to set startingPos less than 
zero, greater than endingPos, or greater than the length of the file. 

It is also invalid to set displayTop to a value greater than the length 
of the file. If displayTop is negative, it will be ignored, and only 
startingPos and endingPos will be used. (This is useful if you want 
the MPW Shell to provide for scrolling only when necessary. If 
displayTop is greater than 0, scrolling will be done on each 
faccess call.) 
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F_GWININFO 


F SWININFO 


F OPEN 


Gets the current window position. Arg is a pointer to a rectangle 
(of type Rect) to store the information. The rectangle is in global 
coordinates. 

Sets the current window position. Arg is a pointer to a rectangle 
(of type Rect) specifying the new size and position. If the window 
size is invalid, or the rectangle is completely off the screen, 
f access returns-1. 

Reserved for operating system use. 


If f access is successful it returns a nonnegative value, usually 0. If the file cannot be 
accessed, f access returns —1. If the requested resource for f gtabinfo, 
f_gfontinfo, or fjsprintrec does not exist for the named file, default values are 
stored and the function returns a value greater than 0. 

MFWC 

int faccess(char *filename, unsigned int cmd, long *arg) 

The cmd constants are declared in the file FCntl.h. If faccess returns with an error, it also 
Sets the value of errno. 

MFW Pascal 

FUNCTION IEfaccess (filename: STRING; cmd: LONGINT; arg: UNIV LONGINT) 
LONGINT; 

The cmd constants are declared in the unit IntEnv. All strings are Pascal strings. 

MFW Assembler 

longint faccess(char *filename, unsigned longint cmd, longint *arg) 

Use die C function faccess. All strings are C strings. The cmd constants are declared in 
the file IntEnv^. If faccess returns with an error, it also sets the value of errno. 
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Signal handling 


The MPW environment provides a set of routines to handle signals. A signal is similar to a 
hardware interrupt in that its invocation can cause program control to be temporarily 
diverted from its normal execution sequence; the difference is that the events that raise a 
signal reflect a change in program state rather than hardware state. Examples of signal 
events are stack overflow, heap overflow, software floating-point exceptions, and 
Command-period interrupts. 

Signal handling is available only for tools that run under the MPW Shell; it is not available 
for applications that run under the Macintosh Finder. 

♦ Note: There are just two software interrupts that can be detected by a program running 
under the current version of the MPW Shell. One is the Command-period, represented 
by the value sigint. The other is abnormal termination by the Abort function, 
represented by the value sigabrt. As additional software interrupts are adde d, new 
values will be added to represent them. The signal-handling procedures will then accept 
these new values. 


The default action of any signal is to close all open files, execute any exit procedures 
(described above under “exit"), and terminate the program. If, however, your tool 
requires special handling of a signal, or chooses to ignore it, you can use the procedure 
signal to replace the default signal handling procedure with your own procedure. 


Signal handling—C 

To access the signal handler in MPW C, do the following: 

■ Include the file Signal.h in your source text 

■ Link your program with the file CRuntime.o. 


♦ Note: The type definition signaiHandier, used later in this section, is not included 
in the file Signal.h. SignaiHandier is equivalent to: 

Typedef void (‘SignaiHandier) (int); 
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Signal handling—Pascal 

To access the signal handler in MPW Pascal, do the following: 

■ Include the statement 

USES {$U Signal.p} Signal 

in your source text. The uses clause and the $u Compiler directive are described in 
the MPW3.0 Pascal Reference. 

■ Link your compilation with the files Runtime.o and PasLib.o. 

The unit Signal declares the following types: 

SignalMap = integer; 

SignalHandler = A longint; 


Signal handling—Assembler 

To access the signal handler, do the following: 

■ Include the file SignaLa in your source text 

■ link your program with the file Runtime.o. 


Signal—specify a signal handler 

void (‘signal (int signum, void (*newHandler)(int)))(int); 

Function signal replaces the current signal handler (the procedure to be executed upon 
receipt of the signal specified in signum) with a user-supplied signal handler. The default 
signal handler may be set or restored by specifying sig_dfl as the current signal handler. 

Some predefined signal handlers may be specified as the newHandier. The function 
sig_ign does nothing. It may be used as the newHandier in a call to signal to 
ignore the signal. The function sig_dfl is the default signal handler. It calls the 
program's exit procedure. 

The newHandier function that is passed to signal takes one parameter (a long 
integer). The parameter is the number of the signal that is currently being handled. Writing 
a signal handler is described below. 

Function signal returns the previous SignalHandler pointer. If this pointer must be 
restored in another part of the program, save the return value and restore it with another 
call to signal. 
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MPW C 

void (*signal (int signum, void (*newHandler)(int)))(int); 

Alternatively, you can use the equivalent: 

Typedef void <*SignalHandler)(int); 

SignalHandler *signal(int signum, SignalHandler *newHandler) 

MPW Pascal 

FUNCTION IEsignal(SigNum: LONGINT; SigHdlr: UNIV SignalHandler): 
SignalHandler; C; 

MPW Assembler 

signalhandler *signal(longint signum, SignalHandler *newHandler) 
Use the C function signal. 


Raise—raise a signal 

int raise(int signum) 

The raise allows signals to be raised under program control. It sends the signal signum 
to the program. It returns 0 if successful, nonzero otherwise. Notice that depending on 
the signal handler installed, raise might not return. 

MPW C 

int raise (int signum) 

MPW Pascal 

FUNCTION IEraise(SIGNUM:LONGINT):LONGINT; C; 

MPW Assembler 

longint raise(longint signum) 

Use the C function raise. 
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Writing a signal handler 

void signalHandler(int signum) 

When a signal is raised, a call is made to the handler specified as the parameter 
newHandier inacallto signal. One parameter is passed to the signal handler. This 
parameter, signum, is the signal number currently being handled. 

When the tool starts, all signal handlers are set to sig_dfl. The action of sig_dfl is as 
follows: 

■ Disable all signals 

■ Call the procedure exit 

To specify your own signal handler procedure, call signal with your procedure as the 
newHandier parameter. When the signal is raised, your procedure will be called. Before 
your procedure is called, the sig_dfl procedure is re-installed as the handler for that 
signal. Therefore, if you want to continue handling the signal, your procedure must re¬ 
install itself with another call to signal at the end of your signal handler. 


A Warning Because s ig_dfl is re-installed as part of the signal-handling 

process, your tool could be interrupted by a second signal that would 
then call sig_dfl. It is safest to disable further signals by calling 
signal (sig_ign) at the beginning of your handler. Then re-install 
the appropriate handler at the end. ▲ 


You can think of signals as operating at the interrupt level. Therefore, the safest signal 
handler would set a global flag, re-install itself, and return. Then in the main body of your 
code, you could check for the flag and do some appropriate actions. 

If you want to terminate program execution because of a signal, do the following: In your 
signal handler, disable that signal (using sig_ign) and set a flag. In the main body of 
your code, you can do some cleanup procedures, and call exit. 

If you install a signal handler for command period, you should return an exit code of-9 to 
the MPW Shell. (For information on returning exit codes, see “Exit”) 
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Signals cannot be raised while executing in ROM or in the MPW Shell. If a signal event 
occurs while executing outside the tool, the signal state is set and the signal handler is 
executed as soon as program control returns to the tool. Because a signal can interrupt the 
tool at any point, there is no protection against heap corruption if a signal handler 
executes calls that modify the state of the heap. Because most buffered I/O potentially 
modifies the heap, writing to standard out or standard error is not recommended in signal 
handlers. 

If you must perform I/O or other operations as a result of a signal, set a flag and check the 
flag during your own processing loop. 
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Chapter 13 Creating a Commando 
Interface for Tools 


YOU CAN CREATE A COMMANDO DIALOG INTERFACE FOR YOUR OWN MPW TOOLS AND 
SCRIPTS. This chapter is a guide to creating the resources Commando requires to 
operate dialogs. The basic use of Commando’s dialogs to operate MPW tools is 
described in Chapter 4. ■ 
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About Commando 


Commando makes it easier to use the MPW tools and scripts, both interactively and for 
composing scripts. A dialog is the programmed interaction between a user and a tool. A 
dialog box is the graphical vehicle used to display the various controls available for a 
tool or script. A dialog may employ several nested dialog boxes. 

You implement the dialog interface for MPW tools by using Commando. This program 
looks in the resource fork of a tool or script for a resource of the type • cmdo•, that is, 
any dialogs to be used by the tool. Commando then loads the resource, builds a dialog list, 
handles events, and passes the command line back to the Shell for execution. 


Invoking Commando 

You can invoke a Commando dialog from the Worksheet in three ways: 

■ Option-Enter: Type the command name and then press Option-Enter. This is the 
easiest method for routine interactive use. 

■ Typ e commando: Type the word commando in front of the command line and press 
Enter. The Commando dialog outputs the command line without executing it. You can 
also use this expression in a script For example, if you don’t want the resulting 
command line to be immediately executed, you can type 

commando toolname 

In this case, Commando will not find a command if the command has been to a 
different name. The tool’s frontmost Commando dialog box is displayed. Clicking the 
Do It button writes the command line to standard output (that is, the window in 
which you typed the command) instead of executing it immediately. This second 
method of using dialog boxes is useful for building command lines that are to be cut 
and pasted into scripts. (The Do It button and other Commando controls are 
described later in this chapter.) 

■ Ellipsis: Type the command name followed by an ellipsis (...) and press Enter. You can 
also use this expression in a script 

The ellipsis may appear anywhere in a command line (except within quotation marks 
or after 3) and it is considered a word-break character. The ellipsis invokes the 
Commando user interface after the Shell has carried out all alias and variable 
substitutions. The entire command line is passed to Commando; the output of 
Commando is then executed by the Shell. 
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♦ Note: To get the ellipsis character, hold down the Option key while simultaneously 
typing the semicolon (;) character. Although three periods closely resemble an 
ellipsis character, Commando won’t be fooled; you must use Option-semicolon to 
get the true ellipsis character that invokes Commando. 

Three Shell variables are used by Commando: 

■ Aliases: This variable lists all defined aliases, with each name separated by a comma. 
The list contains only the names, not the definitions. Commando uses {Aliases} with 
the built-in command Alias. Without this variable Commando would have no way of 
knowing the names of the existing aliases. The variable {Aliases} is exported by the 
Startup script. 

■ Commando: This variable tells the Shell which command to execute when the ellipsis 
character is present in a command line. To use the Commando tool, set the variable 
{Commando} to "Commando." You can use this variable to send the output of other 
tools to the Shell for execution. If the variable does not exist, then the ellipsis is 
removed from the command line and normal execution proceeds. 

■ Windows: This variable lists the current windows, with each name separated by a 
comma. Commando uses this list to redirect input or output to or from existing 
windows. Without this variable Commando would have no way of knowing the names 
of the current windows. The variable {Windows} is exported by the Startup script. 

Throughout this chapter, each type of Commando control is illustrated with an excerpt 

from Cmdo.r, found in the RIncludes folder. 


Creating Commando dialogs 

Here is a procedure for creating your own Commando dialogs: 

1. Create a Commando resource for your tool or script by starting with one of the 
example Commando resources, such as Counir in CExamples or ResEquaLr in 
PExamples. If an existing tool has a Commando control that you want to use, derez 
(that is, decompile by using the resource decompiler DeRez) the cmdo resource, then 
cut it and paste it into your new Commando resource file. 

For example, to examine the Pascal compiler’s cmdo resource: 

DeRez {MPW}Tools:Pascal -only cmdo cmdo.r 

2. Add the Commando resource to your tool or script. For example, 

Rez AddMenu.r -o "{MPWJMPW Shell" -a 
Rez Rez.r -o {MPW}Tools:Rez -a 
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3. Now display the Commando dialogs for your tool or script Adjust the coordinates of 
windows and move or resize the controls by using Commando’s editor (see the next 
section). Edit the Help messages and then derez the cmdo resource. 


Editing Commando dialogs 

In MPW 3.0, Commando offers a built-in editor that lets you edit text labels and help 
messages and graphically move and size the controls within a Commando dialog box. This 
feature makes designing, redesigning, and fine-tuning Commando dialogs much easier. 
Although Commando can move and size controls, controls cannot be created, duplicated, 
or deleted. This means that you still have to manually create the Commando resource, but 
you don’t have to be too concerned about the coordinates and sizes of the controls. 

Once you’ve created the Commando resource, you can simply bring up the Commando 
dialog in edit mode, arrange all the controls to your liking, and then use DeRez to 
decompile the cmdo resource. 

Enabling Commando’s Editor 

To enable Commando’s built-in editor, hold down the command key immediately after 
launching Commando until the Watch cursor appears. Alternatively, you can write -modify 
in the command line, like this 

Commando Rez -modify 

or 

Rez... -modify 


Editing controls 

After you have launched Commando with the built-in editor enabled, it can run in either of 
two different modes: 

■ Normal mode, in which Commando works as usual 

■ Edit mode, in which controls can be dragged and sized. Hold down the Option key to 
put Commando in edit mode. You must also hold down the Option key to select, 
drag, or resize a control. 


CHAPTER 13 Creating a Commando Interface for Tools 393 







Selecting controls 

To select a control, simply press the Option key and click the control. To select multiple 
controls, press the Option and Shift keys together and click each control to be selected. 
You can also click and drag a marquee around a group of controls, as you would in a paint 
program. To unselect a control, click it with the Shift (and Option) key down. 

Basically, selecting controls works exacdy like selecting icons in the Finder, except that 
you must hold down the Option key in Commando. Also, the Commando editor will not 
allow you to select controls outside the user control area. For that reason, the coordinates 
you give when manually creating the Commando resource should fall within the user area. 

Moving controls 

Moving controls works as you would expect hold down the option key as you click and 
drag a control or a selected group of controls. The Commando editor will not allow 
controls to be dragged outside the user control area. Controls cannot be dragged closer 
than two pixels from the boundary. 

You can move selected controls one pixel at a time by holding down the option key and 
pressing the appropriate arrow key. 

You can align the top-left comer of the control to a four-pixel grid by holding down the 
command key while dragging. If you drag a selected group of controls with the command 
key held down, then the top-left comers of each of the selected controls will be aligned to 
the grid. 

Sizing controls 

You size controls by dragging the small gray rectangle in the control’s tower-right comer 
while holding down the Option key. 

Hold down the command key while sizing a control to size the control’s height to the 
recommended Commando height (the sections that follow recommend a height for each 
control that works and looks best). Also, the right edge will align to a four-pixel grid. To 
size the control, simply click the selected control’s grow handle with Option and 
Command keys held (town. List and MultiRegularEntry controls will be sized to the nearest 
whole line. 

Some controls, such as Redirection controls, cannot be resized and have no grow handles. 
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Editing labels 

To edit a text title label, simply select it in the same way you would select a control. You 
can change the text in the same way you change the text for an icon in the Finder. Once 
the title is selected, don’t hold down the Option key to change the text. Text title labels 
are the only labels that can be edited. 


Editing Help messages 

Whenever you select a control, the control’s Help message is locked in the Help window. 
By clicking inside the Help window you can edit the Help message in the same way you 
edit a regular text edit field except that you don’t hold down the Option key. The Help 
message stays locked until another control is selected (and then the new control’s Help 
message is locked) or until all the controls are unselected. 


Changing the size of a Co mman do dialog box 

Once you have enabled Commando’s built-in editor, you can resize any Commando dialog 
box by holding down the Option key while clicking and dragging by the dialog box’s 
lower-right comer (where you would ordinarily find a Grow box in a standard Macintosh 
window). You can also resize nested dialog boxes. However, dialog boxes cannot be 
enlarged beyond the size of the original Macintosh screen. 


♦ Hints and kinks 

Lines and boxes surrounding other controls must be declared later in the 
Commando resource than the controls they surround. You may encounter 
situations in which you have to move a control out of the way in order to 
select a control underneath. 

Controls sized or moved in nested dialogs do not go back to their original size 
or position when you click the nested Cancel button. ♦ 


With the Commando editor enabled, any text entered in a Regular Entry or MultiRegular 
Entry field is saved as the default text. The text will appear the next time Commando is 

invoked. See the sections on Regular Entry and MultiRegular Entry controls later in this 
chapter. 
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Saving the modified Commando dialog 

Once you’ve modified a Commando dialog and clicked the main cancel or Do-It button, 
Commando prompts you with a Save dialog. The Save dialog has three options: 

1. Save the resource. 

2. Don’t save the resource. 

3. Cancel the Save dialog and go back to Commando for more editing. 

When Commando saves the resource, it simply replaces the original resource, wherever it 
came from. The next time you run Commando on the changed resource, the control 
positions and sizes will be where you last left them. You can then use DeRez to decompile 
the cmdo resource to get the actual coordinates or to generate the .r file that will be used 
in a build. 


Strings and Shell variables 

You can dynamically change strings in Commando dialogs by having those strings come 
from Shell variables. To make strings come from Shell variables, define the string like this: 

"{shell variable }" 

The string must begin with a 

*{' 

and end with a 

No leading or trailin g spaces are allowed. The Shell variable must be an exported variable. 

If the variable is undefined at the time the Commando dialog is invoked, the variable 
name with braces will be displayed. 

Any string in the Commando resource, including option strings, help strings, tides, and so 
on, can be a Shell variable. However, strings cannot be embedded within strings; they are 
stand-alone only. 

When Commando is invoked with its built-in editor, Shell variable strings are not 
expanded to the Shell variable values. This is done so that the strings can be edited and 
then saved as Shell variables rather than the values of Shell variables. 

Incidentally, this feature has been used in some of Projector’s Commando dialogs in order 
to display the current user, as shown in Figure 13-1. 
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Figure 13-1 Example use of the {User} variable 


User 







Or {{-1}}, RegularEntry { 

"User", 

{ 81 , 78 , 96 , 113 }, 

{ 81 , 120 , 97 , 294 }, 

"User", ^ _ 

ignoreCase, 

"-u", 

"Enter the name of the current user. If 

"no name is entered, the name in {User} is used." 


Resource description 

Cmdo.r, the resource description file for Commando, is located in {RIncludesJcmdo.r. 


Resource ID and name 

Any resource ID may be used for tools or scripts. Commando uses the first' cmdo' 
resource it finds in die command’s resource fork. 

Commando draws an outlined button, the Do It button, in the lower-right comer of every 
dialog box. The Do It button is labeled with the name of the tool or script (Normally 
Commando uses the name of the tool or script passed from the Shell.) Commando will 
capitalize the first character and force the rest of the characters to lowercase. For 
example, “StackSNiffER” becomes “Stacksniffer.” 

Some people may prefer a different capitalization scheme. If you specify the 
' cmdo * resource of a tool or script with a resource name, Commando will use that namp 
“as is” as the label for the outlined button. This feature should be used sparingly; if you 
rename a tool, the previous name in the resource will still be displayed in the Do It button. 


CHAPTER 13 Creating a Commando Interface for Tools 397 

















Size of the dialog box 


The width of Commando dialog boxes is fixed at 480 pixels. You are free to set the height 
to accommodate the controls in your tool’s dialog box. The number specifying the height 
shouldn’t exceed 295 to be compatible with the smaller Macintosh screens. Specifying this 
height in the ' cmdo ' resource will result in the screen elements shown in Figure 13-2. See 
Table 13-1 for other recommended dimensions. 

Please refer to the array declared under “resource ’cmdo' ” in the sample resource 
description file at the end of this chapter. The area labeled “Options” in Figure 13-2 is the 
area reserved for your controls and options. 


■ Figure 13-2 Basic template for a Commando dialog box 


[ Cancel ] 


r- Option* • 




Command Line¬ 


r-Help- 


The dimensions given below are not policy but recommendations. The sizes of the text- 
edit fields are important if you want to avoid text that shifts up and down slightly when it 
is selected. 
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■ Table 13-1 Summary of recommended sizes for Commando screen elements 


Screen dement 

Recommended size 

Radio buttons 

16 pixels high 

Check boxes 

16 pixels high 

Pop-up menus 

19 pixels high 

Pop-up menu titles 

16 pixels high. Top of title starts 1 pixel below the top 
of the pop-up menu (that is, top of tide = top of pop¬ 
up menu +1 pixel). 

Regular entries 

16 pixels high 

Multi-regular entries 

16 pixels per line 

Editable pop-up menus 

22 pixels high 

Editable pop-up titles 

16 pixels high. Top of tide starts 3 pixels below the 
top of the editable pop-up menu (that is, top of tide 
= top of editable pop-up + 3 pixels). 

Icons 

32 pixels high; 32 pixels wide 

Pictures 

Same relative bounds as the rectangle stored in the 
'PICT* resource 

Tool description 


At the bottom of the Commando dialog box is a three-line Help box. The text in this box 
should be a brief, concise description of the tool, stating what it does. The Help box is 
not scrollable, so you need to limit your text to the confine of the box. See the array 
declared under “resource ' cmdo ' " in the sample resource description file at the end 
of this chapter. 


Regular entry control 


The regular entry control is the most generic control available. The control behaves exacdy 
like the text-edit fields in conventional Macintosh dialog boxes. In addition to strings 
and numbers, the regular entry control can be used for special options that have no 
specified standard control. 

Here is the case declaration for regular entry controls: 
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/* title */ 


case RegularEntry: 

key byte = RegularEntrylD; 

cstring; 

align word; 

rect ; 

rect ; 

cstring; 

byte ignoreCase keepCase; 


cstring; 

cstring; 


/* bounds of title */ 

/* bounds of input box */ 

/* default value */ 

/* the default value is never 
displayed in the Command 
window. If what the user 
types in the textedit window 
matches the default value, 
then that value isn't 
displayed. This flag tells 
Commando whether to ignore 
case when comparing the 
contents of the text edit 
window with the default value 


*/ 


/* 

/* 


option returned.*/ 
help text for entry * 


/ 
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Multiregular entry 


Multiregular entry controls are similar to regular entry controls, except that multiregular 
entry controls accept values that can be entered more than once. For example, most 
compilers accept some type of -define option that can be specified more than once. 

Here is the case declaration for MultiRegular Entry. Note that the cstring for default 
values is the only control that passes its default values to the command line. This is an 
exception to the rule. 


case MultiRegularEntry: /* scrollable lists of an option */ 

key byte = MultiRegularEntrylD; 
cstring; /* title */ 

align word; 

rect; /* bounds of title */ 

rect; /* bounds of input list */ 

byte = $$CountOf(DefEntryList); 
array DefEntryList { 

cstring; /* default values */ 

}; 


cstring; 


/* option returned. Each value will 
be preceded with this option.*/ 


cstring; 


/* help text for entry */ 


Figure 13-3 shows the Defines window in the Rez dialog box with two defines entered. 
Here is the resource control for this function: 


NotDependent {}, MultiRegularEntry { 

"Defines:", 

{ 20 , 35 , 35 , 125 ), 

{ 40 , 30 , 120 , 225 }, 

U, 

"-d", 

"Type in multiple #defines here (such as LANGUAGE=French)" 

}, 

The empty braces after the Defines window coordinates indicates that there are no 
default strings. 
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Figure 13-3 MultiRegular Entry 


Defines: 


debug-true 

language-french 

<> 

<> 



r-Covnmand Line:- 

rez -d debug=true -d language=french 


Check boxes 

The check box control is likely to be the most often used because it corresponds to the 
on/off type options typical of MPW tools. Here is the case declaration for CheckOption: 

case CheckOption: 

key byte = CheckOptionID; 

byte NotSet, Set; /* whether button is set or not */ 

rect; /* bounds */ 

cstring; /* title */ 

cstring; /* option returned */ 

cstring; /* help text for button */ 

The byte Notset or Set is used to set the button’s default state. The option is returned 
only when the button is not its default state. 

This resource code produces the check boxes in Figure 13-4: 

notDependent { }, CheckOption { 

NotSet, { 20 , 10 , 36 , 235 }, ’’Show macro expansions", 

"-print GEN", 

"Expand macros in the listing file." }, 
notDependent { }, CheckOption { 

Set, { 35 , 10 , 51 , 235 }, "Allow automatic page ejects”, 
"-print NOPAGE", 

"Controls whether the Assembler sends automatic page ejects 
to the listing file" }, 
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notDependent { }, CheckOption { 

Set, {50, 10, 66, 235}, "Show warning mesages", 

"-print NOWARN", 

"Controls both the display and count of warning messages." }, 
notDependent { }, CheckOption { 

Set, {65, 10, 81, 235}, "Show macro call statements", 

"-print NOMCALL", 

"Controls the listing of macro call statements." }, 
notDependent { }, CheckOption { 

Set, {80, 10, 96, 235}, "Show generated object code", 

"-print NOOBJ", 

"List generated object code or data for each listed line." }, 
notDependent { }, CheckOption { 

NotSet, {95, 10, 111, 235}, "Show up to 255 bytes of data", 
"-print DATA", 

"Controls whether object data is shown in full ‘ 

(up to 18 lines) or limited to one line." }, 
notDependent { }, CheckOption { 

Set, {110, 10, 126, 235}, "Show macro directive lines", 

"-print NOMDIR", 

"Controls whether macro directives (including conditional 
and set directives) are shown in the listing." }, 
notDependent { }, CheckOption { 

Set, {125, 10, 141, 235}, "Show header lines", 

"-print NOHDR", 

"Controls whether header lines are printed in the listing." }, 
notDependent { }, CheckOption { 

Set, {140, 10, 156, 235}, "Show generated literals", 

"-print NOLITS", 

"Controls listing of literals produce by PEA and LEA machine 
instructions." }, 
notDependent { }, CheckOption { 

NotSet, {155, 10, 171, 235}, "Show assembly status", 

"-print STAT", 

"Controls display of assembly status in the listing." }, 
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Figure 13-4 shows a set of check boxes in their default state and again after the two top 
buttons have been clicked. 


■ Figure 13-4 Setting the CheckOption default state 


Default state of buttons State after top two buttons clicked 


□ Show macro expansions 

£3 Rllow automatic page ejects 
El Show warning messages 
S Show macro call statements 
£3 Show generated object code 

□ Show up to 255 bytes of data 
£3 Show macro directive lines 
El Show header lines 

[3 Show generated literals 

□ Show assembly status 


£3 Show macro expansions 

□ Rllow automatic page ejects 
£3 Show warning messages 

£3 Show macro call statements 
£3 Show generated object code 

□ Show up to 255 bytes of data 
El Show macro directive lines 
£3 Show header lines 

£3 Show generated literals 

□ Show assembly status 


-Command Line: 
asm 


-Command Line:- 

asm -print GEN -print N0PA6E 


Radio buttons 


The simplest set of radio buttons offers several mutually exclusive options. For example, 
the Print Option radio buttons in Figure 13-5 let you choose High or Standard or Draft 
The Standard mode is the default. 


■ Figure 13-5 Radio buttons with default setting 


OHigh 
® Standard 
O Draft 


-Command Line:- 

test 
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Here is the case declaration for radio buttons: 

case RadioButtons: 

key byte = RadioButtonsID; 


byte = $$CountOf(radioArray); 
wide array radioArray { 

/* 

# of buttons */ 

rect; 

/* 

bounds */ 

cstring; 

/* 

title */ 

cstring; 

/* 

option returned */ 

byte NotSet, Set; 

/* 

whether button is set or not */ 

cstring; 
align word; 

/* 

help text for button */ 


}; 

To make the middle radio button the default, as shown in Figure 13-5, declare the middle 
Standard button set: 

notDependent { }, RadioButtons { 

{ 

{115, 300, 130, 400}, "High”, "-q high”, notset, 

"Print the selected files in the highest quality" 
"available from the printer.", 

{132, 300, 147, 400}, "Standard", "~q standard", set, 

"Print the selected files in the normal quality mode.", 
{149, 300, 164, 400}, "Draft", "-q draft", notset, 

"Print the selected files in the fastest way possible" 
"at the expense of quality." 

No option is passed to the command line box because the middle button is explicitly 
declared the default If a button other than the default is clicked, Commando passes the 
appropriate option to the command line, as shown in Figure 13-6. 


■ Figure 13-6 Clicking a button other than the default 

(i) High 
O Standard 
O Draft 

■-Command Line:— 
test -q high 
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Suppose that in the previous example you wanted the default radio button to display its 
option in the command line. You would simply change the order in which you declared the 
radio buttons, so that the middle button would be declared first. Be sure that all buttons 
are NotSet. The result is shown in Figure 13-7. Commando will set the first button that it 
encounters if no button is specified as set 


■ Figure 13-7 No button specified as set 

OHigh 
<•> Standard 
O Draft 

.-Command Line: — 
test -q standard 


♦ Note: A radio button can be either dependent upon or parent to another control. For 
purposes of establishing dependency relations, a cluster of radio buttons is 
considered a single item in die resource listing. See “Control Dependencies” later in 
this chapter for more information. 


Boxes, lines, and text titles 

It is recommended that you group dialog controls or functions within boxes. Commando 
supplies the facilities to draw a box (case Box), to draw a box with a title embedded in 
the upper-left comer (case TextBox), and to create titles in any font (case TextTide). 


♦ Note: When you draw a box around a set of controls, always list the box declaration 
after listing the other controls. Otherwise the Dialog Manager might confuse which 
control is clicked. 
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Box and TextBox cannot depend on other controls, nor can other controls depend on 
them. Commando would not complain if you set up such a dependency, but the line or 
box would not respond to the state of the determining item. TextTitles, on the other 
hand, can be dependent on another control. 


Box 


Use the case Box to draw boxes around controls or to draw lines. To draw lines, make the 
rect 1 pixel wide or 1 pixel high. In other words, to draw a horizontal line, you mi ght set 
the rect to 110,10,11,100}. Here is the case declaration for the Box control: 


case Box: 

key byte = BoxID; 
byte black, gray; 
rect; 


/* Can be used to draw lines too */ 

/* color of object */ 

/* bounds of box or line */ 


TextBox 


The case TextBox lets you draw a box with the title embedded in the line at the upper-left 
comer. This is a frequently used convention in the Commando dialogs. (See the sample 
dialog box template in Figure 13-2.) Here is the case TextBox declaration from the 
Command resource file: 


/* Draws a box with title in upper-left */ 

/* color of object */ 

/* bounds of box or line */ 

/* title */ 

For example, 


case TextBox: 

key byte = TextBoxID; 
byte black, gray; 
rect; 
cstring; 


notDependent { }, TextBox { 
gray, 

{105, 295, 169, 405}, 

"Print Quality" 

} , 

This declaration gives you the results shown in Figure 13-8. 
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■ Figure 13-8 TextBox example 

r-Print Quality—; 

| O High 
\ (•) Standard 
| O Draft 


TextTitle 


Use TextTitle to draw text in any font Here is the case declaration: 


case TextTitle: 

key byte = TextTitlelD; 

byte plain; 

rect; 

int systemFont; 
int systemSize; 
cstring; 


/* style of text */ 

/* bounds of title */ 

/* font number to use */ 
/* font size to use */ 

/* the text to display */ 


For example, let’s write “so cool” in a cool way: 


notDependent { }, TextTitle { 
bold + italic, {20,20,40,100}, 
systemFont, 12, "So Cool..." 

} , 

50 Cool ... 
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Pop-up menus 


Pop-up menus are a convenient way to select an item from a list of related items. 
Commando manages the associated windows, aliases, fonts, and Shell variables. Here is 
the case declaration: 


case Popup: 

key byte = PopUpID; 

byte Window, Alias, Font, Set; 

rect; 

rect; 

cstring; 

cstring; 

cstring; 

byte noDefault, hasDefault; 


/* popup type */ 

/* bounds of title */ 

/* bounds of popup line */ 
/* title */ 

/* option returned */ 

/* help text for popup */ 
/* hasDefault if 1st item 
is "Default Value" */ 


The last field, “byte noDef ault, hasDefault,” tells Commando whether the pop¬ 
up menu has a default value or not. If the pop-up menu does not have a default value, the 
first value in the pop-up list is automatically selected and passed to the command line. If 
the pop-up menu does have a default value, then Commando adds a new item of the form 
“Default Valu? to the front of the list. When this value (such as a font or file) is selected, 
no value is displayed in the window that generates the pop-up menu. 


Here is an example of the resource code for a pop-up menu with a default value. See Figure 
13-9 for the resulting window and pop-up menu. 


notDependent { }, Popup { 
Font, 

{21, 20, 37, 60}, 

{20, 60, 39, 160}, 
"Font", 

"-f ", 

"Popup help message", 
hasDefault 

}, 
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■ Figure 13-9 Pop-up menu with default value 
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Here is the resource code for a pop-up menu with no default value. The results are shown in 
Figure 13-10. 

notDependent { }, PopUp { 

Font, 

( 46 , 20 , 62 , 60 }, 

{ 45 , 60 , 64 , 160 }, 

"Font", 

"-f", 

"popup help message", 
noDefault 

}, 


■ Figure 13-10 Pop-up menu without default value 
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Editable pop-up menus 


Pop-up menus associated with a text-edit box can be edited. You can choose existing 
values from a list and still have the flexibility to enter completely new values. 

case EditPopUp: 

key byte = EditPopUpID; 

/* For Menultem, this EditPopUp must be dependent on 
another EditPopUp of the MenuTitle type so that 
the control recognizes which menu item to display. 

For FontSize, this EditPopUp must be dependent on 
a Popup of the Font type so that the control 
recognizes which sizes of the font exist. */ 

byte MenuTitle, Menultem, /* Type of editable pop-up */ 


FontSize, Alias, Set; 


/* bounds of title */ 

/* bounds of text edit area */ 
/* title */ 

/* option to return */ 

/* help text for text-edit */ 
/* help text for pop-up */ 


rect; 

rect; 


cstring; 

cstring; 

cstring; 

cstring; 


The example in Figure 13-11 shows how the Font Size editable pop-up menu is made 
dependent on the current font. 
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■ Figure 13-11 How Font Size dependency is handled 



If a particular font is selected in the Font box, then the font sizes that actually exist are 
outlined In the example in Figure 13-12 the Monaco font has been selected in the Font 
box. The 9-point item is outlined and has been selected with the mouse. Any font size can 
be typed in the Font Size box. 


■ Figure 13-12 Font Size pop-up menu with font selected 
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Figure 13-13 demonstrates how one editable pop-up menu can be dependent on another. 


■ Figure 13-13 One pop-up menu dependent on another 



notDependent {}, EditPopUp { 
MenuTitle, 

{ 42 , 98 , 59 , 142 }, 

{ 40 , 129 , 68 , 259 }, 

"Menu", 

"-m", 

"Textedit help message", 
"Popup help message" 

}, 

Or {{1}}, EditPopUp { 
Menultem, 

{ 75 , 100 , 91 , 136 }, 

{ 72 , 129 , 94 , 259 }, 

"Item", 

w.J n 

t 

"Textedit help message", 
"Popup help message" 

}, 



* 

File 

Edit 

Find 

Nark 

linmlmi* 




Project f 

Tools 7 

Cmds 
Directory 
Build 


Because the Menultem EditPopUp is dependent on the MenuHtle EditPopUp, the 
Menultem control is dimmed until a menu is selected from the Menu pop-up or until a 
menu is typed in the Menu textedit field. 

After “Project” is selected (Figure 13-13), the Item menu is enabled as shown in 
Figure 13-14. 
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Figure 13-14 Menu title and Item pop-up menus 
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lists 

Use the case list to enable users to make multiple selections from a list of items. Four 
types of things can be listed: 

■ volumes (Inserted disks will be recognized and added to the list.) 

■ shell variables 

■ windows 

■ aliases 

Here is the case declaration for List: 

case List: /* Puts up list of items & allows 


multiple selections */ 


key byte = ListID; 
byte Volumes, ShellVars 


/* what to display in 


cstring; 
cstring; 
align word; 
rect; 
rect ; 
cstring; 


Windows, Aliases; 


the list */ 

/* option to return before each item */ 
/* title */ 


/* bounds of title */ 

/* bounds of list selection box */ 
/* help text for selection box */ 
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Here is the resource code for the two examples shown in Figure 13-15. The second example 
shows that the user has already selected a window. 

notDependent { }, List { 

Volumes, 

r» »t 

r 

"Volumes", 

{ 20 , 30 , 35 , 120 }, 

{ 37 , 30 , 101 , 200 }, 

"Help message" 

}, 

notDependent { }, List { 

Windows, 

"-w", 

"Window List", 

{ 20 , 220 , 35 , 303 }, 

{ 37 , 220 , 101 , 400 }, 

"Help message" 


■ Figure 13-15 List control 


Uolumes Window List 



Three-state buttons 

Three-state buttons were invented to handle the SetFile and SetPrivilege commands. Both 
of these commands deal with the setting or clearing of flags. These commands also have 
another implicit state: “Don’t touch.” Therefore, these buttons have three states: Set, 
Clear, and DontTouch. 
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cstring; 

wide array threeStateArray 
align word; 
rect; 
cstring; 
cstring; 
cstring; 
cstring; 
cstring; 

}; 


/* * of buttons */ 
option returned */ 

/* bounds */ 

/* title */ 

/* for Clear state */ 

/* for DontTouch state */ 

/* for Set state */ 

/* help text for button */ 


case TriStateButtons: 

key byte = TriStateButtonsID; 
byte = $$CountOf (threeStateArray); 

/* 

{ 


Here is the resource code for the example shown in Figure 13-16. 


notDependent { }, TriStateButtons { 

w.a n 

{ 

{40, 25, 58, 135), "Locked", "1", "", "L", 

"This button affects the file \"Locked\" attribute.", 
{58, 25, 76, 135}, "Invisible", "v", "", "V", 

"This button affects the file \"Invisible\" attribute.", 
{76, 25, 94, 135}, "Bundle", "b", "", "B", 

"This button affects the file \"Bundle\" attribute.", 
{94, 25, 112, 135}, "System", "s", "", "S", 

"This button affects the file \"System\" attribute.", 
{112, 25, 130, 135}, "Inited", "i", "", "I", 

"This button affects the file \"Inited\" attribute.", 
{130, 25, 148, 135}, "On Desktop", "d", "", "D", 

"This button affects the file \"On DesktopX" attribute." 

} 

}, 
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■ Figure 13-16 Three-state buttons 
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Command Line: 


setfile -a Lb 


Icons and pictures 

Use the case PictOrlcon to place icons, pictures, or both in the Commando windows. This 
item cannot be dependent on any other item, nor other items on it. Here is the case 
declaration for icons and pictures: 

case PictOrlcon: 

key byte = PictOrIconID; 

byte Icon, Picture; /* display a picture or icon */ 

int; /* resource ID of icon */ 

rect; /* display bounds */ 

The icon in Figure 13-17 is produced by an • icon • resource with an ID of 0, located in the 
system file. 

■ Figure 13-17 Icon in a Commando window 



Here is the resource code that generates the example shown in Figure 13-17: 


notDependent, PictOrlcon { 


Icon, 0, {20, 20, 52, 52} 

}, 
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Control dependencies 


Sometimes one control is dependent on the value of another control. For example, a font 
size control might be dependent on a preceding font selection control. In this case the 
font size control is termed the dependent. The preceding font selection control is called 
the parent because it enables or disables the dependent. 

Commando numbers each item sequentially in the order of its appearance in the resource 
description file. The dependent/parent relationship in Commando is controlled by the 
sequential order of items entered into a Commando resource. 

♦ Note: These numbers do not appear in the resource code; you must count them 
manually. 


An item may be dependent only on other items within the same dialog box. In the case of 
nested dialog boxes, the items in the second and succeeding dialog boxes must be 
renumbered, starting from one. 


Direct dependency 

Usually dependency on another control means that the dependent control is disabled if 
the parent control is disabled (or has no value). 

Figure 13-18 shows two states of a direcdy dependent control. In the first case, nothing 
has been entered in the Type field, so the dependent Creator field is disabled and appears 
dimmed in the dialog box. In the second case, the Creator field is enabled as soon as 
something is typed in the Type field. 

Figure 13-18 also illustrates how the ignoreCase/keepCase flag works. Because the flag is 
keepcase and 'appl' is not equal to • appl 1 (the default value in this case), the option is 
displayed in the Command Line box. 
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Figure 13-18 Direct dependency 
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-Command Line: 
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Inverse dependency 

A control can be inversely dependent on another control. In other words, if the parent is 
disabled, then the dependent is enabled. Or, if the parent is enabled, then the dependent 
is disabled. 

It is also possible for two controls to be inversely dependent on each other. This means 
that both controls are enabled until one is selected; then the other is disabled. For 
example, there are two types of dependencies illustrated in Figure 13-19. The user can 
select either the top check box or the bottom one, but not both; that is, the user is 
allowed to append resources to a resource file or to make the resource map read-only. The 
middle box is enabled only when the top box is checked, because it makes sense to 
replace protected resources only when appending to a source file. 
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Figure 13-19 Inverse dependencies 


i—Append resources to resource file 
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—► □ Make resource file read-only 
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□ OK to replace protected resources 
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^ Make resource file read-only 


Here is the resource description of the three check boxes shown in Figure 13-19- To make 
a control inversely dependent on another control, make the value of the parent negative. 

Or { {-3} }, CheckOption { 

NotSet, 

{20, 10, 40, 350}, 

"Append resources to resource file", 

n _ 2 it 
d / 

"some help text...” 

}, 

Or { {1} }, CheckOption { 

NotSet, 

{40, 10, 60, 350}, 

"OK to replace protected resources", 

"-ov", 

"some help text..." 

}, 

Or { {-1} }, CheckOption { 

NotSet, 

{60, 10, 80, 350}, 

"Make resources file read-only”, 

”-ro”, 

"some help text-.” 

}, 

The second CheckOption (the dependent) is enabled only if the first (the parent) is 
enabled. The third CheckOption is enabled only if the first is disabled. 
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Dependency on the Do It button 

To make the Do It button dependent on something, you must use the special Do It 
Button item in the Commando resource type definition. This item can be specified only 
once per resource and can be specified only in the first dialog. In the example shown in 
Figure 13-20 the Do It button is dependent on the check box. 


■ Figure 13-20 Dependency on the Do It button 


r-Test Options- 
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pCommand Line 
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r Help- 

This tool cannot be executed until the check box is checked. 


Cancel 

Test 


Here is the resource code for the above example: 

NotDependent { }, CheckOption { 
NotSet, 

{20, 20, 40, 200}, 

"Check me baby", 

"-c", 

"Help us to help you.", 

), 

Or { {1} }, DoItButton { 

} 


Multiple dependencies 

A Commando item can be dependent on one or more other items. For example, a control 
might be enabled only when two other controls are enabled. Such situations are 
considered multiple dependencies. 
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Multiple dependencies may be of two types: OR and AND. In an OR dependency, a 
dependent control is enabled if any of its parents is enabled. In an AND dependency, the 
dependent control is enabled only if all its parents are enabled. It is possible to mix ANDs 
and ORs. For example, include an item within an AND or OR list that is dependent on a 
dummy control (case Dummy)—and make the dummy control dependent on another list 
of controls. An example appears in the next section. 


Dependencies on radio buttons 

Commando considers a cluster of radio buttons to be one item. Remember that 
Commando numbers each item sequentially in the order of its appearance in the resource 
description file. When an item is dependent on a specific radio button within a cluster of 
radio buttons, the number of the individual button is placed in the upper four bits of the 
item number that describes the entire cluster of radio buttons. For example, consider a 
radio button duster that is item #5 and contains sue radio buttons. To have a dependency 
on button #3 you would write, in Rez syntax, 

(3«12) + 5 

Figure 13-21 shows three ways in which the check box at the bottom of the dialog box is 
dependent on the upper check box and radio buttons. 


■ Figure 13-21 Dependencies on radio buttons 
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Here is the resource description code describing the operation of the dialog box in Figure 
13 - 21 : 

notDependent { }, CheckOption { 

NotSet, {15, 15, 31, 100}, "Check Me", "-root", "" 

}, 

And { {1, 3} }, CheckOption { 

NotSet, {65, 15, 81, 450}, "Depends on box above and" 
"buttons 1 & 3", "-abovel", "" 

}, 

Or { { (1 « 12) + 4, (3« 12) +4 } }, Dummy { 

}, 

notDependent { }, RadioButtons { { 


{15, 

150, 

31, 

450}, 

"button 

i". 

"-bl". 

NotSet, 

"no help". 

{30, 

150, 

46, 

450}, 

"button 

2", 

"-b2". 

NotSet, 

"no help". 

{45, 

150, 

61, 

450}, 

"button 

3", 

"-b3". 

NotSet, 

"no help". 


} }, 

In Figure 13-21 the first CheckOption is Item #1 in the resource description file and the 
next CheckOption is Item #2 in the same file. Item #3 is a dummy item used to perform 
the complex dependency. Item #4 is the entire cluster of three radio buttons. Item #2 (the 
bottom check box in the sample dialog) is dependent on Item #1 (the top check box) 
AND radio button #1 OR radio button #3. 


Nested dialog boxes 

Complex tools may require more than one dialog box in order to display all the options. 
When there are several nested dialog boxes, all of them are called from buttons in the first 
dialog box. It’s best to avoid calling nested dialog boxes from other nested dialog boxes. 

Figure 13-22 shows how dialog box #2 can be called from dialog box #1. 
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Figure 13-22 Setting up nested dialog boxes 


Dialog #1 calls dialog #2. 


wide array 

itemArray { 

int notDependent =0; /* item dependent upon */ 

switch { 

case NestedDialog: 

key byte 

= NestedDialogID; 


/* the number of the dialog 

to call. It must be greater 
than the current dialog */ 

rect; 

/* bounds of button */ 

cstring; 

/* button's title */ 

cstring; 

/* help text for button */ 



All items in a nested dialog box have an implied dependency on the nested dialog button. 
When a nested dialog button is disabled (dimmed), all the controls in that nested dialog 
act as if they were disabled. 

Figure 13-23 shows the recommended placement of nested dialog call buttons. 
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Figure 13-23 Placement of nested dialog buttons 



User Interface 
recommends 
that nested 
dialog buttons 
begin at the 
lower-right 
and go up. 


While the mouse 
Is held down 
over any control, 
help Info is 
displayed here. 


Clicking the Cancel button in a nested dialog box reverts all its controls to their state 
before the nested dialog box was opened, thus returning the user to dialog box #1. 
Clicking the Do-It button (typically labeled “Continue”) saves the current state of all 
controls in the nested dialog box, and returns the user to the first dialog box. 


Redirection 

Redirection is the easiest control to add to a Commando resource description file. Simply 
specify the type of redirection desired and the point location of the upper-left comer. 

Commando takes care of the rest Here is the case declaration for redirection: 

case Redirection 

key byte = RedirectionID; 

byte StandardOutput, /* the type of redirection */ 

DiagnosticOutput, 

Standardlnput; 

point; /* upper-left point of the entire contraption */ 

Figure 13-23 shows the resource code for Redirection along with its results. 
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■ Figure 13-24 How to obtain input and output redirection 



notDependent {}, Redirection { 
Standardlnput, 

{15, 27} 

}, 

notDependent {}, Redirection { 



{15, 252} 

}, 
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Files and directories 


There are four types of Commando dialogs, offering four different ways to make files and 
directories available: 

■ as individual items for both input and ouput 

■ as multiple files for input only 

■ as multiple files and directories for input only 

■ as multiple new files for output 

Input only means that a standard file dialog box is displayed when the command requires 
a file or directory on which to act. Input or Ouput allows the user to write over an existing 
output file without going through the standard file dialog. 


Individual files and directories 

The Files control enables users to select a single file or directory that can be used for input 
or output. This control supports seven combinations of files, as illustrated in Figure 13-25. 
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Each group of files uses its own case 


Figure 15-25 Resource description for “individual files and directories” controls 


case Files: 


The files control is used to select a single file 
or directory that can be used for input or output 
This control supports seven combinations of files: 



?yte - FilesID; 


InputFile, 

XnputFileOrDir, 

InputOrOutputFile, 

InputOrOutputOrDir, 


OutputFile, 

OutputFileOrOir, 


switch 
ias«^CpFionali J iie: 


These types require the •/ 
•Additional' case below. •/ 


/* These types require the */ 
/* ’NoMore' case below. •/ 


' Using this case makes a popup with two or three items. 
This first item is used to select a default file or to 
select no file. The second (and third) itera(s) are used 
to select input or output files. */ 


key int - 0; 


1 a popup. 

rect; 

/• 

bounds of title */ ^j^|| 

rect; 

/* 

bounds of display box */ 

cstring; 

/* 

title •/ 

cstring; 

/• 

default file */ 

cstring; 

/• 

option to return before file •/ 

cstring; 

/* 

If this item is dependent upon 
another Files item, an extension 
can be specified here to be added 
to the dependents file. */ 

cstring; 

/* 

help text for popup •/ 

byte dim, dontOim; 

/* 

Normally, dependent items are 
dimmed if the parent is disabled, 

if this field is ’•dontOim*’, then 
this item won't be dimmed •/ 


/* These next three strings are the strings displayed in the popup. Most 
of the file types have only two strings but InputOrOutputFile and 
InputOrOutputOrDir require three strings. If a string is set to 
Commando will use a built-in default. */ 
cstring; /* popup item #1 */ 

cstring; /* popup item #2 •/ 

cstring; /* popup item #3 •/ 


case RequiredFile: 

/* Using this case makes a button that goes directly to standard 
file. Use this case when a file is required and the user doesn't 
have the choice of a default file or no file. •/ 
key int - 1; 

rect; /• bounds of button •/ 

cstring; /• title of button •/ 

cstring; /• option to return before file */ 

cstring; _ /• help text for button •/ _ 


This case generates! 
a button. 


}; 

/* Some file types take additional information. See the comment next to the 
file types to find out which case to choose here. •/ 
switch ( 


case Additional: 

key byte - 0; 
cstring; 

/* For InputOrOutputFile, an option 

cstring FilterTypes - 

can be specified when a new 
(or output) file is chosen. •/ 

;/* preferred file extension (i.e. ".c") 

cstring; 

If null, no radio buttons will be 
displayed. If FilterTypes is used, 
the radio buttons will toggle 
between showing files only with 
the types below and all files */ 

/• title of only files button •/ 

cstring; 

/* title of all files button •/ 

byte - $$CountOf (TypesArray) ;/• up to 4 types may be specified •/ 

align word; 
array TypesArray { 
literal longint text - 

•TEXT', /* desired input file type, specify •/ 

obj - 

•OBJ ', /* no type for all types •/ 

appl - 

•APPL’, 

da - 

•DFIL', 

tool - 

J; 

•MPST'; 


case NoMore: 
key byte - 1; 
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Here is the resource code for the “individual files and directories” controls that appear in 
Figure 13-25. 


notDependent { } , Files { 

InputFile, 

OptionalFile { 

{20,20,40,130}, 

{20,100,40,300}, 

"C Input Files", 

ti •• n u it it 
999 

"Help message here.", 
dim, 

"Read Standard Input", 
"Select a file to compile...", 

n n 

9 

}, 

Additional { 

It It 

9 

".c", 

"Only files that end in .c”, 
"All text files", 

{text} 

}, 

}, 

Or {{1}}, Files { 

OutputFile, 

OptionalFile { 

{50,20,70,100}, 

{50,100,70,300}, 

"Object File", 

"c.o", "-o", ".o", 

"Help message here.", 
dontDim, 

"Send object code to c.o", 
"Select an object file-.", 

II it 

9 

}, 

NoMore {}, 
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Figure 13-26 shows the control resulting from the resource code above. The control is 
shown first in its default state, then as it appears after the user selects an input file, and 
finally as it appears after Commando produces the object file associated with the input 
file selected by the user. 


Figure 13*26 Examples of “individual files and directories” controls 

Default state 


C Input File 
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Object File pi ^ 


Select a file.to compile. 
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Object file dependent on input 


C Input File 
Object File 


hd:...:Commando:checkBoK.c 


hd:...Commando:checkBoK.c.o 


Multiple files and directories for input and output 

Use the case MultiFiles (shown here) to enable users to select multiple files and directories 
for input and output. Note the four cases representing subtypes within the case MultiFiles: 

■ case MultilnputFiles 

■ case MultiDirs 

■ case MultilnputFilesAndDirs 

■ case MultiOutputFiles 


430 MPW 3.0 Reference 






















Here is the MultiFiles case: 


case MultiFiles: 

key byte = MultiFilesID; 


cstring; 
cstring; 
align word; 
rect; 
cstring; 

...Cstring; 
switch { 


/* button title */ 

/* help text for button 




/* bounds of button */ 

/* message like "Source files 
to compile:" */ 

/* option returned before each filename 
Can be Null */ 


case MultilnputFiles: 
key byte = 0; 

byte = $$CountOf (MultiTypesArray); 
align word; 

array MultiTypesArray { 

literal longinit text = 'TEXT', 

obj = 'OBJ ', 
appl = 'APPL', 
da = 'DFIL', 
tool = 'MPST'; 


/* up to 4 types may be 
specified */ 


/* desired input file 

type, specify no type */ 
/* for all types */ 


cstring FilterTypes = 


cstring; 

cstring; 


/* preferred file extension 
(that is, ".c"). If null, 
no radio buttons will be 
displayed. If FilterTypes 
is used, the radio buttons 
will toggle between show¬ 
ing files with only the types 
below, and all files. */ 

/* title of only files button */ 
/* title of all files button */ 


case MultiDirs: 
key byte = 1; 


case MultilnputFilesAndDirs: 
key byte = 2; 


case MultiOutputFiles: 
key byte = 3; 

}; 
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Figure 13-27 is a Files dialog box controlled by resource code using the MultiFiles case. 
Here is the resource code: 


notDependent {}, MultiFiles { 

"Description Files..."/ 

"Select resource input files to compile"/ 
{60/ 330/ 80/ 468}/ 

"Resource Description Files:"/ "" , 
MultilnputFiles { 

{text}/ 

n y- n 
. i / 

"Files ending in .r", 

"All text files" 

1 , 


The button "Resource Description Files..." is the Rez dialog box that displays 
the large standard file dialog box shown in Figure 13-27. The last two tides refer to the two 
radio buttons. 


■ Figure 15-27 Example of multiple input files 
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In the example in Figure 13-27 two resource files have just been added. When a file 
extension is specified, two radio buttons allow you to see only those files that have the 
specified extension or all files, regardless of their extension. In either case, only files that 
have a file type matching one of the those specified in the resource are displayed. Up to 
four file types may be displayed. If no file type is specified, all files are eligible for 
display. 

If no file type or file extension is specified in the * cmdo • description, then no radio 
buttons are displayed, as shown in Figure 13-28: 

notDependent {}, MultiFiles { 

"Files to delete...", 

"Select files to delete", 

{60, 330, 80, 468), 

"Files to delete:", 

”-d" , 

MultilnputFiles { 

U, 

”", /* no file extension specified */ 

ft t» 

r 

tt ii 

), 

}, 
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Figure 13-28 Example of multiple input files with no file extension specified 


Q Commando! 


D 3stateCDEF.c 

O 
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D 3stateC OEF.h 


□ 3stateCDEFBMap.a 


L J 

D checkBoH.c 
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D cmdl.r 


k_-_ / 

□ cmdo.h 



□ Cmdo.map 


Done 

D cmndButtons.c 



□ cmndUlindour.c 

s 

Cancel 


Files to delete: 



Sometimes the type of a file is more important than the file’s extension. The Link tool, 
for example, identifies object files by the file type (' ob j ') rather than by the file 
extension. By specifiying FilterTypes as the extension string, the radio buttons will 
toggle between showing files matching the specified types and showing all files, regardless 
of type. Here is an example of this behavior: 

notDependent {}, MultiFiles { 

"Files to link-.", 

"Select files to link", 

{60, 330, 80, 468}, 

"Files to link:", 

n_7 n 

f 

MultilnputFiles { 

{'OBJ •}, 

FilterTypes, 

"Only object files", 

"All files" 

>, 

}, 
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Figure 13-29 Example of multiple input files with object files specified 


e=>HD 

[ lEH ) 
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<§> Only object files Q All files 
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Files to link: 
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O 
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In Figure 13-29, TESampleGlue.a.o is the only file in the CExamples directory that has a 
type of' obj •. After the “All files” radio button is clicked, all files in the CExamples 
directory are displayed, as shown in Figure 13-30. 
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Figure 13-30 Example of multiple input files with all files specified 


Q CExamplesj 


D TESample.h 

□ TESample.make 

D TESample.r 

□ TESampleGlue.a 

<> 

cd HD 

( £js<t 

Driue 

D TESampleGlue.a.o 


D TestPerf.c 

□ TubeTest.c 

□ TubeTest.make 

O TubeTest.r 

H 

0 

Done 

[ Cancel ] 

O Only object files ® nil files 

Files to link: 





li 1 


<> 

( Bemope ] 


Multiple files and directories for input only 

Here’s how you can use the case MultiFiles to enable the user to select multiple directories 
for input only. 

NotDependent {}, MultiFiles { 

"Include Paths-.", 

"Help message for directory button.", 

{ 110 , 330 , 130 , 468 }, 

"Include Search Paths:", 

tl.e ft 

5 r 

MultiDirs {}, 

}, 

The first item in the above code, "include Paths-." , is the button in a frontmost 
dialog box (Rez was used in this example) that generates the file dialog box shown in 
Figure 13-31. “Include Search Paths:” is the title of the scrollable window at the bottom of 
the dialog box. Two Includes folders have just been selected from the upper window and 
added to the Include Search Paths window just below. 
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Figure 13-31 Multiple directories for input 
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CD AStructMacs 

CD CExamples 

CD Clncludes 
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s 
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[ Done ] 

[ Cancel ] 

Include Search Paths: 
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2 
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Another file dialog box is used to select multiple files and directories. This dialog box 
appears in Figure 13-32. Here is the resource code that produces this dialog box. 

NotDependent {}, MultiFiles { 

"Files to duplicate-.", 

"This button brings up a dialog allowing" 

"selection of files and directories to duplicate.", 
( 25 , 50 , 45 , 230 }, 

"Files and Directories to duplicate:", 

«• «v 

f 

MultilnputFilesAndDirs {} 

}, 
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Figure 13-32 Example of a “directories” control for multiple input files 


Add Current Directory: ] 


QMPIHl 



Multiple new files 

The case Multifiles also gives the user the ability to select multiple files for output. 
Here is the resource code resulting in the example shown in Figure 13-33. 

notDependent { }, MultiFiles { 

"New Files-.", 

"Help message for button", 

{ 110 , 330 , 130 , 468 }, 

"New files to open:", 

"-n", 

MultiOutputFiles { }, 

}; 
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Figure 13-33 Using the MultiOutputFiles subcase of the case MultiFiles 


■ 



Version 


You can place a version string in your Commando dialogs for your own identification 
purposes, as shown in Figure 13-34. The version string is centered below the Do-It button. 
Here is the declaration for VersionDialog: 
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case VersionDialog: 


/* Display a dialog when the version # 
is clicked */ 

key byte = VersionDialogID; 
switch { 

case Versionstring: /* Version string embedded right here */ 

key byte = 0; 

cstring; /* Version string of tool (e.g. V2.0) */ 


case VersionResource: 

key byte = 1; 
literal longint; 

integer; 

}; 

cstring; 

align word; 

integer noDialog; 


/* Versions string comes from another 
resource */ 

/* resource type of pascal string 
containing version string */ 

/* resource id of version string */ 

/* Version text for help window */ 

/* Rsrc id of 'DLOG' */ 


If there is no modal dialog to display when the version string is clicked, set the resource ID 
to zero (noDialog). 

If the version string comes from another resource (VersionResource), the string must be 
the first thing in the resource, and the string must be a Pascal-style string. An 1 str 1 
resource is an example of a resource that fits the bill. 

If the modal dialog is to have a filter procedure, the procedure must be linked as an 
• fitr' resource with the same resource ID as the dialog. 


■ Figure 13-34 Version string 
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The version string may be embedded in the commando resource using the Versionstring 
case or the version string may come from a resource using the VersionResource case. If the 
version comes from a resource, the resource must contain a Rez-style pstring. You can 
use this with the SetVersion tool to read SetVersion’s 'mpst 1 resource. 

As usual, the help string is a string that is displayed when the version string is clicked. 
Typically, this help string contains more detailed author/version information. 

For extra flair, a dialog may be zoomed out when the version string is clicked. If a dialog 
is specified, you must give the resource ID of the * dlog • resource (found in the resource 
fork of your tool or script) to display. Commando simply calls ModalDialog() with that 
dialog. 

If you want to have a custom filter procedure, you must compile the filter procedure as a 
standalone resource with a resource type of ’ f itr • and with the same id as the • dlog » 
resource. The visible/invisible flag in the dlog resource should be set to invisible. 
Commando will move the ' dlog * window so that the bounds rect specified in the 
• dlog ' are relative to the bounds of the Commando dialog. 
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♦ Note: If you do not specify a VersionDialog commando item, Commando attempts to 
add one for you by looking for a ' vers ’ resource with an ID of 1. If found, 
Commando displays the short version string under the Do-It button. When the version 
string is clicked, Commando displays the long version string in the help window. If a 
•vers' (i) resource is not found, Commando looks fora * vers' (2) resource. 
If one is not found, no version string is displayed. 


A Commando example 

The best way to learn how to make a Commando interface is to study an actual 
Commando resource for an existing MPW tool. Choose a tool, explore the operation of 
the controls in its Commando dialog, and then use DeRez to generate a readable version 
of the tool’s Cmdo.r resource. 

To obtain the Commando resource for a tool, use this syntax: 

DeRez {MPW}Tools:toolname Cmdo.r -only cmdo 

To obtain the Commando resource for a Shell command, use this syntax: 

DeRez " {MPW}MPW Shell" Cmdo.r -only "'cmdo' (9"Commandname8") " 

For your convenience, the Commando resource for ResEqual, called ResEqual.r, is shown 
here. You can find this file in the PExamples folder. 
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♦include "cmdo.r" 
resource 'cmdo' (355) { 

{ 

240, 

"ResEqual compares the resources in two files and reports 
the differences.", 

{ 

NotDependent {}, Files { 

InputFile, 

RequiredFile { 

{40, 40, 60, 190}, 

"Resource File 1", 

n n 

r 

"Select the first file to compare.", 

}, 

Additional { 

n n 

9 

FilterTypes, 

"Only applications, DA's, and tools", 
"All files", 

{ 

appl, 

tool, 

da 

} 

} 

}, 

Or {{1}}, Files { 

InputFile, 

RequiredFile { 

{70, 40, 90, 190}, 

"Resource File 2", 

n t» 

9 

"Select the second file to compare,", 

}, 

Additional { 

««n 

9 

FilterTypes, 

"Only applications, DA's, and tools", 
"All files", 

{ 

appl. 
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tool 

da 


}; 


NotDependent {}, TextBox { 
gray, 

{30, 35, 95, 195}, 

"Files to Compare" 

}, 

NotDependent {}, CheckOption { 

NotSet, 

{105, 75, 121, 155}, 

"Progress”, 

"-p", 

"Write progress information to diagnostic" 
"output." 

}, 

NotDependent {}, Redirection { 

StandardOutput, 

{40, 300} 

}, 

NotDependent {}, Redirection { 

DiagnosticOutput, 

{80, 300} 

}, 

NotDependent {}, TextBox { 
gray, 

{30, 295, 121, 420}, 

"Redirection" 

) 9 

Or {{2}}, DoItButton { 

Jr 


The above resource code generates the frontmost dialog box of ResEqual, which appears 
in Figure 13-35. 
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Figure 13-35 A Commando example: frontmost ResEqual dialog box 
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Chapter 14 Performance-Measurement Tools 


MPW 3.0 PROVIDES A SET OF PERFORMANCE-MEASUREMENT TOOLS to aid 
professional software developers in measuring and improving the performance of 
their applications. This chapter explains how to use these tools and provides a 
detailed example. The PerformReport tool is also described in Part D. ■ 
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Movable code resources 470 
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About performance-measurement tools 


In essence, the performance-measurement tools sample the Program Counter (PC) register 
just often enough to obtain a statistically accurate estimate of the program’s actual use of 
time. The code is divided into “buckets” of two or more bytes and a count of sampled PC 
values for each bucket during the program's execution is output to a text file. You can 
then analyze these results by running a report generator, PerformReport. PerformReport 
merges the output file with a linkmap of the measured code resources to produce a list of 
procedures, sorted by the number of PC samples found within the procedure. 

▲ Warning The performance-measurement tools are designed for temporary 

inclusion in an application, desk accessory, or driver for purposes of 
measuring performance. They are not designed for inclusion in 
commercial products, because they rely on low-level system 
mechanisms that are not guaranteed to function correctly on all future 
machines. ▲ 


The memory management strategy for the performance tools is based on the assumption 
that developers wishing to measure performance will likely have a machine larger than the 
smallest target machine for their applications. Thus, they can use performance tools that 
require some additional memory without severely impacting the application’s memory 
management strategy. 

The best way to use these tools depends upon your particular environment and the code 
you want to test These considerations are discussed in the section “Implementation 
Issues” later in this chapter. You will need to temporarily insert calls to the performance 
tools within your code. Examples of the placement of these calls are provided in MPW C 
and MPW Pascal. Be sure to remove these calls when you have completed your 
optimizations. 
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Components of performance tools 


The performance tools consist of the following pieces: 

■ A library file (PerfonnLib.o): This file is in the {Libraries} folder. Link with this file. 

■ Interface files for Pascal (Perf.p) and C (Perf.h): These files are in the interface 
folders {PInterfaces} for Pascal and {CIncludes} for C. These are the files that you use 
or include in the source files for your application. These interfaces depend only on the 
standard Macintosh memory types files: MemTypes.p for Pascal and Types.h for C. 

An assembly-language interface has not been provided for the performance tools. 
Assembly-language programmers can use either the Pascal or the C interface. Both go 
directly to the Pascal and assembly-language implementation in PerformLib.o. 

■ Sample programs, makefiles, and instructions for execution: These files are in 
the Examples folders: {MPW}Examples:PExamples: for Pascal, and 
{CExamples}Examples:CExamples: for C. Instructions for running the performance 
tools sample programs are included in the Examples folders. 

■ PerformReport (a tool for analyzing performance data and producing reports): 

This tool is found in the {MPWjTools: folder. For detailed information about the tool, 
see the command pages in Part n. For detailed instructions on how to run this tool, 
see the instructions in the appropriate Examples folder. Examples of the output from 
this tool are discussed below. 

■ ROM map files: You’ll find a number of ROM maps in the folder {MPWpROM Maps', 
including MacIIROM.map, MacSEROM.map, and MacPlusROM.map. These files are 
combined with the link map file for your application, to add location information for 
the OS and Toolbox routines to the performance data. You will usually append the 
appropriate ROM maps to your application's link map for input to the tool 
PerformReport. 
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Requirements for using performance tools 

To use the performance tools, you need to add calls to these routines in your application, 

desk accessory, or driver. They are described later in more detail: 

■ InitPerf specifies the types of measurements to be performed, and allocates storage. 
This should be called once near the beginning of your code. 

■ TermPerf stops measurements (if active), and frees the storage. TermPerf must be 
called once after InitPerf succeeds, and measurement is finished. 

■ PerfControl starts and stops measurements. Perfcontrol must be called once 
(after InitPerf) to start measurements. Use PerfControl to avoid taking 
measurements in idle loops, dialog boxes, alerts, and other places where the user 
response time determines performance. 

■ PerfDump stops measurements (if active), and writes the performance data to an 
output file. You should call PerfDump after measurements are collected for reporting. 


How performance measurement works 

The performance-measurement tools are designed to give you useful information about 
the performance of a program without severely altering the user responsiveness or memory 
requirements—that is, without changing the characteristics of what is being measured. 
However, the act of measurement necessarily alters what is being measured in the ways 
summarized below. 


Program Counter sampling 


The fundamental idea behind the performance-measurement tools is to samp le the 
Program Counter (PC) register frequently enough to obtain a statistically accurate 
estimate of the actual program performance, but infrequendy enough so that overall 
performance is not affected. The performance-measurement tools use the Vertical 
Blanking signal (VBL) on 64K ROMs and the Time Manager on 128K and larger ROMS. 

The Time Manager allows 1 ms resolution in sampling, but this imposes about a 20 percent 
performance degradation. A value of 4 ms to 10 ms reduces the performance degradation 
to 4 percent to 10 percent. Use of the VBL signal on old ROMs imposes a sampling rate of 
approximately 60 times per second (16 ms). 
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Restrictions 


If your application directly uses the VIA Timerl (or some software that uses it, such as the 
sound generator or the Time Manager) then you might not be able to use these 
performance-measurement tools. 

In the case of old ROMs, the performance-measurement tools may not work correctly with 
programs that make use of VBL tasks. 

If you are r unnin g the performance tools under MultiFinder, you may need to increase the 
sampling interval. 

A Warning If you set the sampling interval too low for your machine, the 

performance tools may crash or cause your program to run very slowly. 
It is best to start with a high sampling interval, such as 10 ms or 20 ms, 
and decrease it only after experience allows you to predict the effect 
of the shorter interval. For example, if measurements taken with a 
sampling rate of 10 ms cause your program to run 10 percent slower, 
then it is probably safe to increase the sampling rate to every 5 ms at a 
cost of having the program run 20 percent slower. ▲ 


Bucket counts 

The performance tools require 2 bytes of memory for a counter for each “bucket” of code 
that is measured. For instance, for a 100K tool or application, using a bucket size of 16 
bytes, about 12,800 bytes are required for the counters. If the ROM is measured, an 
additional 8K, 16K, or 32K bytes (for 64K, 128K, or 256K ROMs) is required. 

If your program spends a substantial amount of time outside CODE segments and ROM, 
then you may want to measure RAM “misses.” Because RAM can be quite large, a second 
(generally larger) bucket size can be specified for RAM “misses.” And you can control the 
amount of RAM to be measured by using a low address to start setting up buckets and a 
hi gh address for the last bucket If the RAM misses are measured, additional memory is 
required. 

The sum of all memory required for counters is allocated as a single contiguous block at 
the time initPerf is called. For this reason, you should call initPerf fairly early in 
your initialization, before memory becomes fragmented. 
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In addition to the memory for bucket counters, the performance tools will use one master 
pointer for a handle to some information, and will allocate a few small structures with 
NewPtr calls. 


Using performance-measurement tools 

This section presents a detailed explanation for each of the seven steps necessary to 
install the performance-measurement routines into your code. For each step the specifics 
for using these tools with MPW C and MPW Pascal are under separate subheadings. 

You need make only a few changes to install these tools in your code. The changes are 
basically the same, whether you are developing an application, a desk accessory, an MPW 
tool, or a driver. It is even possible to install performance tools in ROM. 

Here are the steps: 


1. Install tinder conditional compilation 

After measuring the performance of your program, you will probably want to make 
changes, test the changes for correctness, and then repeat the measurements to verify the 
performance improvements. While making and testing changes, it is very important not to 
include the performance tools, unless you are confident that the changes do not introduce 
any new bugs. If your code terminates early for any reason, then the normal system 
recovery techniques (in MacsBug, calls such as G SysRecover under the MPW Shell or ES 
from an application) do not work. In such a case, within a few milliseconds after the 
system tries to reuse the memory occupied by the performance tools, a timer interrupt 
occurs and a system error or crash results. The system error will probably force rebooting 
the system. For this reason, it is advisable to include the performance-measurement tools 
under a conditional flag. 

♦ Note-. In the steps that follow, it is assumed that all the performance measurement 
changes are surrounded by conditional compilation. However, in the code fragments 
that follow, the actual conditional compilation statements are omitted to save space. 
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MPWC 


/* 

♦define PERFORMANCE to turn on the measuring tools. 

#undef PERFORMANCE to turn off the measuring tools. 

*/ 

♦define PERFORMANCE 

Calls to the performance tools routines can then be surrounded by the following 
conditional compilation statements: 

♦ifdef PERFORMANCE 
♦endif PERFORMANCE 

MPW Pascal 

{$SETC DoPerform := true} {false to exclude Performance Tools} 

Calls to the performance tools routines can then be surrounded by the following 
conditional compilation statements: 

{$IFC DoPerform} 

{$ENDC} 


2. Include the interface 

In the main body of your MPW C code, you need to include the header file for the 
performance tools, like this: 

♦include <Perf.h> 

In the main body of your MPW Pascal code, you need to reference the interface file for 
the performance tools, like this: 

USES 

MemTypes, 

Perf; 
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3. Provide a pointer to a block of variables 

For an application or MPW tool, you can declare a global variable. If you are developing a 
desk accessory, driver, or ROM that does not have global variables, then you need to be 
somewhat creative in finding a location for the pointer. The choices include: a local 
variable on the stack (assuming the stack frame will persist long enough), a field of a 
block allocated and locked down in the heap, or a low memory location. In any event, the 
address of the location allocated for the pointer must be passed to the performance 
routines, as indicated in the following steps. 

MPW C 

TP2PerfGlobals ThePGlobals; 


MPW Pascal 

VAR thePerfGlobals: TP2PerfGlobals; 


4. Initialize the performance-measurement tools 

Somewhere near the beginning of your code’s execution, and when large chunks of 
memory are available, you need to initialize the performance tools. 


▲ Warning Once your code has initialized the performance routines successfully, 
it is important that you call the termination routine described in Step 
7 before your code terminates. Failure to do so almost always results in 
a fatal system crash. ▲ 

MPW C 

ThePGlobals = nil; 

if (! initPerf (&ThePGiobais, ... otherparameters ...)) { 

/* report error in initialization and terminate */ 

}; 

The function initPerf allocates a block on the heap for the performance global 
variables if ThePGlobals is nil. If the ThePGlobals is not nil, InitPerf assumes 
the block is already allocated. 
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MFW Pascal 

thePerfGlobals := NIL; 

if not initPerf (thePerfGlobals, .. otherparameters ...) THEN 
BEGIN 

{Report error in initialization and terminate.} 

END; 

When you set the pointer thePerfGlobals to nil, initPerf allocates a block on the 
heap for the performance global variable. If the pointer is not nil, initPerf assumes 
the block is already allocated. 


5. Turn on the measurements 

After initialization succeeds, you can start measurements at any point in your code. The 
call that starts (and stops) measurements returns the current on-off state as a Boolean 
value. 

You can call Perf control with a second argument of f ai se in order to turn 
performance measurements off. This is useful for disabling sections of code that you 
don’t want to measure, such as the event loop of an application, a dialog box where user 
response time dominates the compute time, parts of the application that rely on the VIA 
timer, and so on. 

MFW C 

(void)PerfControl(ThePGlobals r true); 

MFW Pascal 

VAR OldState: boolean; 

OldState := PerfControl (thePerfGlobals, true); 

Alternatively, you may use: 

IF PerfControl(thePerfGlobals, true) 

THEN {dummy THEN statement}; 
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6. Dump the results 

When you reach the end of the code to be measured, you must make a all to have the 
performance counters written into a text file. If the dump routine encounters any I/O, 
memory management, or other system errors, it returns a nonzero return code. You can 
examine this code to determine the nature of the problem. 

MPW C 

OSErr err; 

err = PerfDump (ThePGlobals, "\pPerform.out", ...Otherparameters) ; 
if (err != noErr) 

/* Code to report erros during dump */ 

The Perf Dump routine takes the output-filename as a Pasal string. If the empty string is 
passed, the name defaults to Perform.out. 

MPW Pascal 

VAR err: OSErr; 

err := Perf Dump (thePerfGlobals, 'Perform, out 1 , ...Otherparameters) ; 
If err <> noErr 

THEN {Report errors during dump}; 

If the empty string is passed for a filename, the name will default to Performout. 


7. Terminate cleanly 

After dumping the counters to a text file, you must terminate the performance- 
measurement tools cleanly. TermPerf removes the interrupt routine and frees the 
memory associated with the performance global variables and counters. 

MPW C 

TermPerf(ThePGlobals); 


MPW Pascal 

TermPerf(thePerfGlobals); 
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MPW performance tools routines 


This section gives detailed information about MPW C and MPW Pascal parameters to the 
performance tools routines. The C and Pascal calls are presented first, followed by 
discussion relevant to both. 


The function InitPerf 

Here is the MPW C declaration for InitPerf: 
pascal Boolean InitPerf( 


TP2PerfGlobals 

*thePerfGlobals, 

short 

timerCount, 

short 

codeAndROMBucket Si ze, 

Boolean 

doROM, 

Boolean 

doAppCode, 

const 

Str255 appCodeType, 

short 

romID, 

const 

Str255 romName, 

Boolean 

doRAM, 

long 

ramLow, 

long 

ramHigh, 

short 

ramBucketSize 


); 

Here is the MPW Pascal declaration for InitPerf: 


FUNCTION InitPerf ( 

VAR thePerfGlobals: 

TP2PerfGlobals 

time rCount, codeAndROMBucket Size 

: integer- 

doROM, doAppCode: 

boolean; 

appCodeType: 

Str255; 

romID: 

integer; 

romName: 

Str255; 

doRAM: 

boolean; 

ramLow, ramHigh: 

longint; 

ramBucketSize: 

integer 

) : boolean; 
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Call the function initPerf once to set up the performance-monitoring interrupt handler 
and to allocate the memory area for counters. The function returns true if initialization is 
successful, and false if it encounters errors. 

The function initPerf takes a number of parameters: 

■ thePerfGiobais is the address of the pointer to the global variable area. If the 
value of the pointer is nil, a new block of global variables is allocated on the heap. 

■ timercount (for new ROMs) determines the number of milliseconds between PC 
samples. For most applications, good values are: 

a 10 ms for Macintosh Plus and Macintosh SE, when running under the Find er, Under 
MultiFinder, allow 20 ms. 

□ 4 ms for Macintosh II, running under the Finder. Under MultiFinder, allow 10 ms. 

♦ Note: For old (64K) ROMs, timercount is the number of VBL events (16 ms each) 
between PC samples. 

■ codeAndROMBucket si ze sets the bucket size for user code (and the ROM, if ROM 
measurement is requested). A separate parameter sets the bucket size for RAM, as 
described below. The bucket size may be any integer greater than or equal to 2. 

♦ Note: The performance tools force the bucket size to be a power of 2 by rounding 
this parameter up to the nearest power of 2. 

If the bucket size is set as low as 2, individual instructions are measured. However, this 
requires a lot of memory—an amount equal to the amount of code (and ROM) being 
measured. 

A more practical value for this parameter is 8, which requires only 25 percent of the 
memory being measured. Even larger bucket sizes may be used if memory is scarce, 
although the resolution of the measurements becomes an issue at some point. 

■ doROM determines whether the ROM code as well as the user's code are measured. A 
value of true causes the ROM code to be measured. 

■ doAppc ode determines whether or not user code is measured. A value of t rue causes 
user code to be measured. 

■ appCodeType is a Pascal string that determines the resource type of user code to be 
measured. For application programs this should be ' code • (in Pascal) or n \pcoDE" 

(in C); for desk accessories it should be • drvr • (in Pascal) or" \pdrvr" (in C); and 
so on. Resources of the specified type are obtained from the current (top-level) 
resource file. 

■ romiD indicates ROM types. You’ll normally pass a romiD of 0, indicating the use of 
one of the predefined ROMs. Table 14-1 shows the predefined ROM IDs and names. 
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■ Table 14-1 Predefined ROM IDs and names 


Computer 

ROM ID 

ROM name 

Macintosh 128K 

$69 

ROM 

Macintosh XL 

$FF 

ROMXL 

Macintosh Plus 

$75 

ROMPLUS 

Macintosh 512e 

$75 

ROMPLUS 

Macintosh SE 

$76 

ROMSE 

Macintosh n 

$78 

ROMII 

Macintosh IIx 

$78 

romii (unchanged from Macintosh II) 


ROM IDs and the following parameters are mainly to support older or newer ROMs not in 

Table 14-1. 

■ roniName indicates a ROM name other than one of the predefined names listed in 
Table 14-1. This value is usually the empty string, indicating the use of a predefined 
ROM name. This parameter can be used to specify the name of older or newer ROMs. 

■ doRAM determines whether RAM misses are measured. A value of t rue invokes 
measurement 

■ ramLow specifies the lower limits of RAM to measure for misses. This parameter has 
no effect unless doRAM is true. 

■ ramHigh specifies the upper limit of RAM to measure for misses. This parameter has 
no effect unless doRAM is true. 

■ ramBucketsize specifies the bucket size to use for measuring RAM misses. This 
parameter has no effect unless doRAM is t rue. 

A “RAM miss” is a PC sample that is not contained in any of the user code segments or the 

ROM. 


The function PerfControl 

Here is the MPW C declaration for Perf control: 

pascal Boolean PerfControl( 

TP2PerfGlobals thePerfGlobals, 
Boolean turnOn 

); 
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Here is the MPW Pascal declaration for Perfcontroi: 

FUNCTION PerfControl( 

thePerfGlobals: TP2PerfGlobals; 
turnOn: boolean 
) : boolean; 

The Perfcontroi function returns the previous state. You must call Perf control 
once to begin performance measurements. It can be called more frequendy to avoid 
measuring uninteresting areas of code, such as idle loops or dialog boxes. 

■ thePerfGlobals points to the global variable area, initialized by a successful call to 

INITPERF. 

■ turnon turns measurements on (t rue) and off (false). 


The function PerfDump 


Here is the MPW C declaration of PerfDump : 


pascal short PerfDump( 
TP2PerfGlobals 
const Str255 
Boolean 
short 

); 


thePerfGlobals, 

reportFile, 

doHistogram, 

rptFileColumns 


Here is the MPW Pascal declaration of PerfDump: 


FUNCTION PerfDump( 

thePerfGlobals: 
reportFile: 
doHistogram: 
rptFileColumns: 
): integer{OSErr}; 


TP2PerfGlobals; 
Str255; 
boolean; 
integer 


The function PerfDump dumps the statistics gathered by the performance tools into a 
text file suitable either for direct analysis or for processing by PerformReport. PerfDump 
calls Perfcontroi to turn off measurements and accepts the following parameters: 

■ thePerfGlobals points to the global variable area, initialized by a successful call to 

InitPerf. 


■ reportFile specifies the name of the report file. If this is the empty string, the 
default name Perform.Out is used. 


CHAPTER 14 Performance-Measurement Tools 46l 




■ doHistogram (if true) places a histogram after the bucket counts in the data file. 
The histogram consists of a number of asterisks for each bucket, normalized so that 
the bucket with the largest number of hits receives a line of asterisks out to 
rptFileColumns. 

■ rptFileColumns controls the number of columns in the report file. It has no effect 
unless doHistogram is true. 


The function TermPerf 

Here is the MPW C declaration of TermPerf : 

pascal void TermPerf(TP2PerfGlobals thePerfGlobals); 

Here is the MPW Pascal declaration of TermPerf: 

PROCEDURE TermPerf(thePerfGlobals: TP2PerfGlobals); 

If the call to initPerf succeeds, then TermPerf must be called before terminating the 
program. Otherwise, a system crash results because the timer interrupt, which is still 
enabled, will jump to points unknown. TermPerf removes the interrupt handler and frees 
the storage used by the counters with the parameter thePerfGlobals. This parameter 
points to the global variable area, initialized by a successful call to initPerf. 
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Performance reports 


When your code has completed its execution, you call PerfDump to generate a 
performance output file showing the results of the bucket counts. You can analyze this 
data by using the tool PerformReport. Examples of both the performance output and 
report files appear in this section. See Part n for a command page describing the tool 
PerformReport. 


Performance output file 

The results of the performance tests are output to a performance data file when 
PerfDump is called. This file is a text file containing the bucket locations and counts. 
You should call PerfDump at the very end of the test, so that no interference with 
program I/O should occur. The performance output file is not opened until PerfDump is 
called. 

Below is an example of a performance output file as generated by a call to PerfDump. 
Some repeated lines have been omitted, as indicated by 

Notice that the performance data is arranged on a per segment basis. Only nonzero 
buckets are reported; in other words, missing buckets had a hit count of zero. 
(PerfDump has an option to produce a histogram (bar graph) to the right of the Hits 
column. That option was not exercised in this example.) 
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Performance Parameters 


Bytes per bucket, Code and ROM: 8 
Bytes per bucket, RAM: 4 
Sampling Interval: 4 ms 

Performance Summary 


Total hits outside of the sampled segments: 2 
Maximum hits in one bucket: 872 
Total hits in all buckets: 3222 

Performance Data 


Offset Hits | Segment 117 size 20000 


52F8 

1 

1 

5300 

1 


53C8 

12 

1 

53E8 

1 

1 

53F0 

2 

1 

5400 

1 

1 

5428 

1 

1 

5728 

872 

1 

• • • 

1B830 

9 

1 

1B838 

53 

1 

1B840 

41 

1 

1B848 

61 

1 

1B850 

41 

1 

Offset 

Hits 

I Segment 253 size 1FFFFF 

D6A0 

1 

1 

287D0 

40 

1 


1E6134 1 | 

1E8990 1 | 

1FB20C 101 I 


Offset Hits | Segment 13 size B68 name STDIO 


Offset Hits | Segment 12 size 71E name SACONSOL 
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Offset Hits | Segment 5 size 


DO name ROMSEG2 


70 

2 

i 







88 

5 

i 







90 

10 

i 







BO 

4 

i 







B8 

2 

i 







CO 

3 

i 







Offset 

Hits 

i 

Segment 

4 

size 

136 

name 

ROMSEGl 

10 

9 

i 







18 

3 

i 







20 

5 

i 







110 

19 

i 







118 

58 

i 







120 

46 

i 







Offset 

Hits 

i 

Segment 

3 

size 

8C 

name 

SEG2 

50 

3 

i 







58 

3 

i 







60 

9 

i 







68 

1 

i 







70 

14 

i 







78 

1 

i 







Offset 

Hits 

i 

Segment 

2 

size 

DO 

name 

SEG1 

10 

2 

i 







18 

18 

i 







20 

4 

i 







A8 

7 

i 







B0 

12 

i 







B8 

18 

i 







Offset 

Hits 

i 

Segment 

1 

size 

101C 

name 

Main 

F38 

43 

i 







F40 

116 

i 







F48 

78 

i 







F50 

19 

i 







F58 

77 

i 







F60 

66 

i 







F68 

56 

i 
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Analyzing the results with PerformReport 

Once the performance data file has been generated, you are ready to run the report 
generator, a tool called PerformReport. This tool merges the performance output file 
with a linkmap of the measured code resources to produce a list of procedures, sorted by 
the number of PC samples found within the procedure. (See Part II for more information 
on PerformReport.) An example of the contents of this file is shown here. 

If your call to initPerf had the parameter do Rom set to true, then you’ll need to append 
the correct ROM map file to your application's link map before running 
PerformReport. For example: 

Link -o YourApp —1 >LinkMap YourApp.p.o _.etc... 

YourApp # run your application, generate Perform.Out 
Catenate {MPWJ'ROM Maps': romName.Map » LinkMap 
PerformReport -1 LinkMap -m Perform.Out 


PerformReport — Merges Linker Output and Performance Dump January 30, 
1989 

Reading Link Map file: "LinkMap" 

Reading Performance Measurements file: "Perform.Out" 

PerformReport Parameters: 

8 bytes per bucket, ROM and CODE. 

4 bytes per bucket, RAM. 

2 hits outside code measured. 

3224 hits total, 0.0% outside the segments. 

872 maximum hits in one bucket. 
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Procedures by possible hits 
Num Segment : Procedure 


(showing Probable % 


Def 

497 


117 

Main 

: 

117 

Main 

: 

117 

Main 

2 

117 

Main 

: 

1 

Main 

: 

. .1 

Main 

. 

4 

ROMSEG1 

: 

117 

Main 

: 

117 

Main 

: 

117 

Main 

: 


ATRAP68020 

CHKSLOT 

DSPATCH 

RSECT 

%I_MUL4 

%1_DIV4 

ROMWIOO 

LVL1INT 

TFSDISPATCH 

LVL2INT 


0 
0 

474 
399 

0 3 

5 0 

1 0 

1 0 

0 0 

67.6% 32.1% 


of time): 
Poss Prob% 

872 28.9% 
872 13.5% 
872 0.0% 
26 15.1% 
56 12.8% 

5 0.6% 
0 0 . 1 % 
1 0 . 0 % 
0 0 . 0 % 
1 0 . 0 % 

99.8% 


Total Reported = 


Prob 

436 

436 

0 

13 

14 


PerformReport: That's All Folks! 


Adding identification lines to a data file 

After displaying a title line, and giving the names of the files being read, PerformReport 
has an option (*e) to echo lines from the head of the measurements file until the phrase 
“Performance Data" is encountered. This option allows you to add identification lines at 
the head of performance-measurement files. Various parameters are gathered from lines 
that begin with special keywords. Here are the keywords with the phrases they head: 

Bytes Bytes per bucket 

Total Total hits 

Maximum Maximum hits 

Performance Performance Data 

You are free to add comment lines at the head of a data file, as long as the comment lines 
do not begin with these keywords. 
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Interpreting the performance report 

Perf ormReport translates the bucket hit information into procedure-based 
information. Because procedures can span buckets, there may be some uncertainty about 
how bucket hits are related to procedure hits. Perf ormReport attempts to deal with 
this uncertainty by classifying hits into several categories: 

Definite When a bucket is completely contained in a single 

procedure, all hits in the bucket are counted as definite 
hits in that procedure. 

Possible/Probable When a bucket is partially contained in several 

procedures, all hits in the bucket are counted as possible 
hits in each procedure; in addition, the hits in the 
bucket are counted as probable hits in a particular 
procedure, based on the amount of the bucket that is 
covered by the particular procedure. 

Please realize that the concept of probable hits is not intended to give an accurate 
statistical picture of the situation. What happens in practice is that buckets are 
frequently covered by two procedures, and almost all of the hits occur in one procedure or 
the other. The intent behind “possible and probable” hits is to give you some feeling for 
the accuracy of the resulting data. 

If the Pascal example TestPerf.p is modified to have a bucket size of 8, then the possible 
hits will be few relative to the definite hits. The exception is the %i_div4 procedure, 
which will have zero definite hits, but shares a bucket with %i_mul4. In fact there are no 
divide operations in the sample program; therefore all hits apparently belonging to 
%i_div4 really belong to the multiply operations. 

If the percentage of definite hits becomes too low, you should consider reducing the 
requested bucket size. 


Implementation issues 

The performance tools have been designed to work “as is” for most common application, 
desk accessory, and driver runtime environments. However, because Macintosh has an 
open architecture, it is possible that actions taken or assumptions made by application 
code will conflict with die needs of the performance tools. This section discusses possible 
conflicts, and how to resolve them. 
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Locking the interrupt handler 

You must lock down both code and data for the performance tools while taking 
performance measurements. Code for the trap handler must be locked down because the 
timer interrupts occur asynchronously. Data for the counters must be locked down 
because handles cannot be assumed to be valid during interrupt processing. The data area 
for counters cannot be “grown” at interrupt time, because the heap may be inconsistent. 


Segmentation 

The code that must be locked down at execution time has been placed in segment “Main” 
and occupies about 1 kilobyte of space. This is because segment “Main” is usually 
guaranteed not to be unloaded at run time. 

If your application’s “Main” segment is too full to allow the performance tools to be 
linked correctly, then you may retarget the code in PerformLib.o by using the Lib tool. 
However, your application must not have an “unload all segments” routine in its idle 
procedure. One good segment to retarget to is “PerfMain”, because this segment contains 
some of the other pieces of the performance tools. 

These MPW commands illustrate how to retarget the code in PerformLib.o: 

Duplicate {Libraries}PerformLib.o temp 

Lib -o {Libraries}PerformLib.o -sn Main=PerfMain temp 

Delete temp 

The first command line creates a copy of PerformLib.o in temp. The second line replaces 
the original PerformLib.o with the output of Lib. The -sn option causes all code originally 
placed in segment “Main” to be in segment “PerfMain”. The third line deletes the file temp. 


Dirty CODE segments 

Because A5 is not valid at interrupt time, and there are no low memory globals assigned to 
performance measurement, the interrupt routine stores some data values in its code 
space, including the pointer to the locked-down data. Thus, if your application uses 
checksums to detea code segments attacked by errors, the performance tools will cause 
erroneous checksum failures. The easiest fix is simply not to checksum the “Main” 
segment (or whichever segment you choose). 
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Moveable code resources 


The code for the trap handler, and the data area for the counters, must be locked down 
during performance measurement 

In counting “hits” in code resource segments, the performance interrupt routine checks 
that the handle to a measured resource is locked. If it is not locked, the resource is 
assumed to be “unloaded” and PC values are not checked for being within the resource. 

The performance tools call stripAddress, among other A-traps. If you are using A-tiap 
breaks in MacsBug (as with the athc command), you may get an A-trap from within the 
Performance Tool’s interrupt handler, and MacsBug may state that the heap is corrupt. 
The heap might not actually be corrupt, but simply inconsistent at interrupt time. 
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Appendix A Macintosh Programmer’s 
Workshop Files 


This appendix lists all of the files provided with the Macintosh 
Programmer’s Workshop 3.0. The files are listed as they appear on the 
distribution disks. (Volume names are shown in bold; directory names begin and 
end with a colon.) MPW Assembler, MPW Pascal, MPW C, and MPW C++ are 
separate products. ■ 


Contents 

MPW 3.0 files 473 

Distribution disk MPW Installation Disk: 
Distribution disk MPW1: 473 
Distribution disk MPW2: 474 
Distribution disk MPW3: 475 
Distribution disk MPW4: 476 
MPW Assembler files 477 

Distribution disk MPW Assemblerl: 477 
Distribution disk MPW Assembled: 477 
MPW Pascal files 478 

Distribution disk MPW Pascall: 478 
Distribution disk MPW Pascal2: 479 
MPW C files 481 

Distribution disk MPW Cl: 481 
Distribution disk MPW C2: 482 
Hard disk configuration 484 


473 


471 






MPW 3.0 files 


Distribution disk MPW Installation Disk: 

MPW Installation Disk: 

Outside Bug Reporter Application used to document bugs 


MPW Installation Disklnstallation Folder 


Backup 

Dolt 

errorFile 

'MPW Installer 1 

Startup 

Worksheet 


Tool used by MPW Installer to copy files 
Script that shows each file copied 
File used for error redirection 
MPW Shell used for installation procedure 
Script that controls the installation 


Distribution disk MPW1: 

MPW1: 

'MPW Shell' The MPW Shell program 

MPW.Help Command syntax descriptions (for Help command) 

Quit Quit MPW script 

Resume Script to resume MPW after executing an application 

Startup Script to initialize MPW Shell 

Suspend Script to suspend MPW to run an application 

SysErrs.Err Indexed error message file (used by Shell and tools) 
UserStartup Customizable startup script called by Startup 
Worksheet Worksheet contents saved from last session 
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Distribution disk MPW2: 


MPW2:Examples:Examples: 


AddMenus 

ChecklnActive 

CheckOutActive 

DerezPict 

Instructions 

Lookup 

'Startup, etc.' 

State 

'Unix Aliases' 


Add menu to MPW menu bar 
Check in the active window to Projector 
Check out the active window from Projector 
Derez a PICT data file 


MPW2£xamples:Projector ExamplesrSample: 

ProjectorDB Projector database 

MPW2:Examples:Projector Examples:Sample:Commands: 

ProjectorDB Projector database 


MPW2:Examples:Projector Examples:Sample:Utilities: 
ProjectorDB Projector database 


MPW2:Interfaces:RIn eludes: 


Cmdo.r 
MPWTypes.r 
Pict.r 
SysTypes.r 
Types.r 


Commando graphic interface resources 
MPW-specific resource type definitions 
Resource type definition for PICT 
System resource type definitions 
Common resource type definitions 


MPW2:Libraries:Libraries: 


DRVRRuntime.o 

HyperXLib.o 

Interfaces 

ObjLib.o 

PerformLib.o 

Runtimes 

SERD 

Stubs.o 

ToolLibs.o 


Driver runtime library 

Libraries for HyperCard XCMD’s and XECfTs 
Inside Macintosh interface library 
Object-oriented programming library 
Library for performance-measurement tools 
Runtime library for Assembler and Pascal 
Serial driver resources 
Stub routines to make MPW tools smaller 
MPW tool library (spinning cursor, error manager) 
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MFW2:R0M Maps: 

MacIIROM.map 

MacPlusROM.map 

MacSEROM.map 


MPW2:Scripts: 

BuildCommands 

BuildMenu 

BuildProgram 

CCvt 

CompareFiles 

CompareRevisions 

CreateMake 

DirectoryMenu 

Dolt 

Line 

MergeBranch 

OrphanFiles 

SetDirectory 

TransferCKID 

UserVariables 


Automated build commands 

Generates menu for use with automated build commands 

Automated build 

Converts 2.0 C source to 3.0 

Compares two files side by side 

Compares two revisions of the same file 

Generates a makefile to build a prog ram 

Generates Directory menu 

Highlights and executes a series of Shell commands 

Locates line number (useful with other tools and scripts) 

Merges a branch revision onto a project’s trunk 

Removes Projector information from files 

Command to set current directory 

Move Projector information from one file to another 

Use Commando to set all user variables 


Distribution disk MPW3: 


MPW3:Tools: 

AboutBox 

Backup 

Canon 

Canon.Dict 

CCvtMxL.dict 

CCvtUMx.dict 

Choose 

Commando 

Compare 

Count 

DeRez 

DumpCode 

DumpFile 
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DumpObj 

Entab 

FileDiv 

GetErrorText 

GetFileName 

GetListltem 

Lib 


Distribution disk MFW4: 


MFW4iTools: 


Link 

Make 

MakeErrorFile 

Matchlt 

PerformReport 

Print 

ProcNames 

ResEqual 

Rez 

RezDet 

Search 

SetPrivilege 

SetVersion 

Sort 

Translate 

Wherels 
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MPW Assembler files 


Distribution disk MPW Assemblerl: 

MPW Assemblerl:Examples:AExamples 

Count.a 

Count.r 

FStubs.a 

Instructions 

MakeFile 

Memory .a 

Sampler 

Sample.h 

Sample.incl.a 

Sample.make 

SampleMisc.a 

Sample.r 

MPW Assemblerl:Tools 
Asm 


Distribution disk MPW Assembled: 

MPW Assembler2:Interfaces ^Includes: 

ApplDeskBus.a 

ATalkEqu.a 

FixMath.a 

FSEqu.a 

FSPrivate.a 

Graf3DEqu.a 

HardwareEqu.a 

HyperXCmd.a 

IntEnv.a 

ObjMacros.a 

PackMacs.a 

PaletteEqu.a 

PickerEqu.a 

PrEqu.a 
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PrintCallsEqu.a 

PrintTrapsEqu.a 

Private.a 

PrPrivate.a 

QuickEqu.a 

ROMEqu.a 

SANEMacs.a 

SANEMacs881.a 

ScriptEqu.a 

SCSIEqu.a 

ShutDownEqu.a 

SignaLa 

SlotEqu.a 

SonyEqu.a 

Sound.a 

Sy$Equ.a 

SysErr.a 

TimeEqu.a 

ToolEqu.a 

Traps.a 

VideoEqu.a 


MPW AssembIer2:InterfacesiA5tructMacs: 

FlowCtlMacs.a 

ProgStrucMacs.a 

Sample.a 

Sampler 


MPW Pascal files 


Distribution disk MPW Pascall: 

MPW Pascall:Iibraries:PLibraries: 

PasLib.o 

SANELib.o 

SANELib881.o 
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MPW Pascall:TooIs: 


Pascal 

PasMat 

PasRef 


Distribution disk MPW Pascal2: 

MPW Pascal2:Examples:PExamples: 

EditCdev.make 

EditCdev.p 

EditCdev.r 

FStubs.a 

Instructions 

MakeFile 

Memory.p 

Memory.r 

ResEqual.p 

ResEqual.r 

Sample.h 

Sample.make 

Sample.p 

Sample.r 

SillyBalls.make 

SiliyBalls.p 

TESample.h 

TESample.make 

TESampIe.p 

TESample.r 

TESampleGlue.a 

TESampleGlue.a.o 

TestPerf.p 

TubeTest.make 

TubeTest.p 

TubeTest.r 

MPW Pascal2:Interfaces:PInterfaces: 

AppleTalk.p 
Controls.p 
CursorCtl.p 
Desk.p 
DeskBus.p 
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Devices.p 

Dialogs.p 

DisAsmLookUp.p 

Disklnit.p 

Disks.p 

ErrMgr.p 

Errors.p 

Events.p 

Files.p 

FixMath.p 

Fonts .p 

Graf3D.p 

HyperXCmd.p 

IntEnv.p 

Lists.p 

MacPrint.p 

Memory.p 

MemTypes.p 

Menus.p 

Notification.p 

Objlntf.p 

OSEvents.p 

OSIntf.p 

OSUtils.p 

Packages.p 

Packlntf.p 

PaletteMgr.p 

Palettes.p 

PasLiblntf.p 

Perf.p 

Picker.p 

Pickerlntf.p 

Printing.p 

PrintTraps.p 

Quickdiaw.p 

Resources.p 

Retrace.p 

ROMDefs.p 

SANE.p 

Scrap.p 

Script, p 

SCSI.p 

SCSIIntf.p 

SegLoad.p 

Serial.p 

ShutDown.p 
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Signal.p 

Slots.p 

Sound.p 

Start.p 

Strings.p 

SysEqu.p 

TextEdit.p 

Timer.p 

Toollntf.p 

ToolUtils.p 

Traps.p 

Types.p 

Video.p 

Videolntf.p 

Windows.p 


MPW C files 


Distribution disk MPW Cl: 


MPW Cl:Iibraries:CLibraries: 

CInterface.o 

CLib881.o 

Complex.o 

Complex881.o 

CRuntime.o 

CSANELib.o 

CSANELib881.o 

Math.o 

Math881.o 

StdCLib.o 


MPW Cl:Tools: 
C 
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Distribution disk MFW C2: 


MPW C2:Examples:CExamples: 

Count.c 

Count.r 

EditCDEV.c 

EditCDev.make 

EditCdev.r 

FStubs.c 

Instructions 

MakeFile 

Memory.c 

Memory.r 

Sample.c 

Sample.h 

Sample.make 

Sample.r 

SiUyBalls.c 

SillyBalls.make 

TESample.c 

TESample.h 

TESample.make 

TESample.r 

TESampleGlue.a 

TESampleGlue.a.o 

TestPerf.c 

TubeTest.c 

TubeTest.make 

TubeTest.r 


MPW C2:Interfaces:CIndudes: 

AppIeTalk.h 

Asserth 

Complex.h 

Controls.h 

CType.h 

CursoiCtUi 

Desk.h 

DeskBus.h 

Devices.h 

Dialogs.h 

DisAsmLookUp.h 

Disklnit.h 
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Disks.h 

ErrMgr.h 

ErrNo.h 

Errors.h 

Events.h 

FCntl.h 

Files.h 

FixMath.h 

Float.h 

Fonts.h 

Graf3D.h 

HyperXCmd.h 

IOCll.h 

Limits, h 

Lists.h 

Locale.h 

Math.h 

Memory.h 

Menus.h 

Notification.h 

OSEvents.h 

OSUtils.h 

Packages.h 

Palette.h 

Palettes.h 

Perf.h 

Picker, h 

Printing.h 

PrintTraps.h 

Quickdraw.h 

Resources.h 

Retrace.h 

ROMDefs.h 

SANE.h 

Scrap.h 

Script.h 

SCSI.h 

SegLoad.h 

Serial.h 

Setjmp.h 

ShutDown.h 

Signal.h 

Slots.h 

Sound.h 

Start.h 

StdArg.h 
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StdDef.h 

StdIO.h 

StdLib.h 

String.h 

Strings.h 

SysEqu.h 

TextEdit.h 

Time.h 

Timer.h 

ToolUtils.h 

Tiaps.h 

Types.h 

Values.h 

Video.h 

Windows.li 


Hard disk configuration 


HardDisfeMPW: 

Examples: 

interfaces: 

:Libraries: 

':ROM Maps:' 
:Scripts: 

:Tools: 

'MPW Shell' 

MPW.Help 

Quit 

Resume 

Startup 

Suspend 

SysEns.Err 

UserStartup 

Worksheet 
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HardDisk:MPW:Examples: 


:AExamples: 

:CExamples: 

:ExampIes: 

:HyperXExampIes: 

:PExamples: 

':Projector Examples:' 


HardDisk:MPW:Examples ^Examples: 

Count.a 

Count.r 

FStubs.a 

Instructions 

MakeFile 

Memory.a 

Sampler 

Sample.h 

Sample.incl.a 

Sample.make 

Sample.r 

SampleMisc.a 


HardDisk;MPW:Examples:CExampIes: 


Count.c 

Count.r 

EditCDEV.c 

EditCDev.make 

EditCdev.r 

FStubs.c 

Instructions 

MakeFile 

Memory.c 

Memory.r 

Sample.c 

Sample.h 

Sample.make 

Sample.r 

SillyBalls.c 

SillyBalls.make 

TESample.c 

TESample.h 
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TESample.make 

TESample.r 

TESampleGlue.a 

TESampleGlue.a.o 

TestPerf.c 

TubeTest.c 

TubeTest.make 

TubeTestr 

HardDisk:MPW:Examples:Examples: 

AddMenus 

ChecklnActive 

CheckOutActive 

DerezPict 

Instructions 

Lookup 

'Startup, etc.' 

State 

'Unix Aliases' 


HardDisk:MPW:Examples:HyperXExamples: 

HardDisfcMPW:Examples:PExamples: 

EditCdev.make 

EditCdev.p 

EditCdev.r 

FStubs.a 

Instructions 

MakeFile 

Memory.p 

Memory.r 

ResEquaLp 

ResEquaLr 

Sample.h 

Sample .make 

Sample.p 

Sample.r 

SillyBalls.make 

SillyBalls.p 

TESample.h 

TESample.make 

TESample.p 

TESample.r 

TESampleGlue.a 
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TESampleGlue.a.o 

TestPerf.p 

TubeTest.make 

TubeTest.p 

TubeTest.r 

HardDisk:MPW:Examples:Projector Examples: 

:Sample: 

HardDlsk:MPW:Examples:Projector Examples:Sample: 

:Commands: 

:Ulilities: 

ProjectorDB 

HardDisk:MPW:Examples:Projector Examples:Sample:Commands: 
ProjectorDB 

HaidDisk:MPW:Examples:Projector Examples:SampleUtillties: 
ProjectorDB 

HardDisk:MPW:Interfaces: 

:AIncludes: 

:AStructMacs: 

:CIncludes: 

:PInterfaces: 

:RIncludes: 

HardDisk:MPW:Interfaces:AIflcludes: 

ApplDeskBus.a 

ATalkEqu.a 

FixMath.a 

FSEqu.a 

FSPrivate.a 

Graf3DEqu.a 

HardwareEqu.a 

HyperXCmd.a 

IntEnv.a 

ObjMacros.a 

PackMacs.a 

PaletteEqu.a 

PickerEqu.a 

PrEqu.a 
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PrintCallsEqu.a 

PrintTrapsEqu.a 

Private .a 

PrPrivate.a 

QuickEqu.a 

ROMEqu.a 

SANEMacs.a 

SANEMacs881.a 

ScriptEqu.a 

SCSIEqu.a 

ShutDownEqaa 

Signals 

SlotEqu.a 

SonyEqu.a 

Sound.a 

SysEqu.a 

SysErr.a 

TimeEqu.a 

ToolEqu.a 

Traps.a 

VideoEqu.a 

HardDisk:MFW:Interfaces:AStructMacs: 

FlowCtlMacs.a 

ProgStrucMacs.a 

Sampler 

Sampler 

HardDisk:MPW:Interfaces:CIndudes: 

AppleTalk.h 

Asserth 

Complex.h 

Controls.h 

CType.h 

CursorCd.h 

Desk.h 

DeskBus.h 

Devices.h 

Dialogs.h 

DisAsmLookUp.h 

Disklnit.h 

Disks.h 

EirMgr.h 

ErrNo.h 
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Errors.h 

Events.h 

FCntl.h 

Files.h 

FixMath.h 

Float.h 

Fonts.h 

Graf3D.h 

HyperXCmd.h 

IOCtl.h 

Limits.h 

Lists.h 

Locale.h 

Math.h 

Memory .h 

Menus.h 

Notification.h 

OSEvents.h 

OSUtils.h 

Packages.h 

Palette.h 

Palettes.h 

Perf.h 

Picker.h 

Printing.h 

PrintTraps.h 

Quickdraw.h 

Resources.h 

Retrace.h 

ROMDefs.h 

SANE.h 

Scrap.h 

Script.h 

SCSI.h 

SegLoad.h 

Serial.h 

Setjmp.h 

ShutDown.h 

SignaLh 

Slots.h 

Sound.h 

Start.h 

StdArg.h 

StdDef.h 

StdIO.h 

StdLib.h 
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String.h 

Strings.h 

SysEqu.h 

TextEdit.h 

Time.h 

Timer.h 

ToolUtils.h 

Traps.h 

Types.h 

Values.h 

Video.h 

Windows.h 


HardDisk:MPW:Interfaces:PInterfaces: 

AppleTalk.p 

Controls.p 

CuisoiCtI.p 

Desk.p 

DeskBus.p 

Devices.p 

Dialogs.p 

DisAsmLookUp.p 

Disklnit.p 

Disks.p 

ErrMgr.p 

Errors.p 

Events.p 

Files.p 

FixMath.p 

Fonts.p 

Graf3D.p 

HyperXCmd.p 

IntEnv.p 

Lists.p 

MacPrint.p 

Memory.p 

MemTypes.p 

Menus.p 

Notification.p 

Objlntf.p 

OSEvents.p 

OSIntf.p 

OSUtiis.p 

Packages.p 


490 MPW 3.0 Reference 



Packlntf.p 

PaletteMgr.p 

Palettes.p 

PasLiblntf.p 

Perf.p 

Picker.p 

Pickerintf.p 

Printing.p 

PrintTraps.p 

Quickdraw.p 

Resources.p 

Retrace.p 

ROMDefs.p 

SANE.p 

Scrap.p 

Script, p 

SCSI.p 

SCSIIntf.p 

SegLoad.p 

Serial.p 

ShutDown.p 

Signal.p 

Slots, p 

Sound.p 

Start.p 

Strings.p 

SysEqu.p 

TextEdit.p 

Timer.p 

Toollntf.p 

ToolUtils.p 

Traps.p 

Types.p 

Video, p 

Videolntf.p 

Windows.p 


HardDisk:MPW:Interfaces:RIndudes: 

Cmdo.r 

MPWTypes.r 

Pict.r 

SysTypes.r 

Types.r 
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HardDisk:MPW:Iibraries: 

:CLibraries: 

:Libraries: 

:PLibraries: 

HardDisk:MPW:Libraries:CLibraries: 

CInterface.o 

CLib881.o 

Complex.o 

Complex881.o 

CRuntime.o 

CSANELib.o 

CSANELib881.o 

Math.o 

Malh881.o 

StdCLib.o 

HardDlsk;MPW:Iibraries:Libraries: 

DRVRRuntime.o 

HyperXLib.o 

Interface.o 

ObjLib.o 

PerformLib.o 

Runtime.o 

SERD 

Stubs.o 

ToolLibs.o 

HardDisk:MPW:Iibraries:PLibraries: 

PasLib.o 

SANELib.o 

SANELib881.o 

HardDisk:MPW:ROM Maps: 

MacIIROM.map 

MacPlusROM.map 

MacSEROM.map 
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HardDisk:MPW:$cripts: 

BuildCommands 

BuildMenu 

BuildProgram 

CCvt 

CompareFiies 

CompareRevisions 

CPlus 

CreateMake 

DirectoryMenu 

Dolt 

Line 

MergeBranch 

OrphanFiles 

SetDirectory 

TransferCKID 

UserVariables 

HardDi$k:MPW:Tools: 

AboutBox 

Asm 

Backup 

C 

Canon 

Canon.Dict 

CCvtMxL.dict 

CCvtUMx.dict 

CFront 

Choose 

Commando 

Compare 

Count 

DeRez 

DumpCode 

DumpFile 

DumpObj 

Entab 

FileDiv 

GetErrorText 

GetFileName 

GetListltem 

Lib 

Link 

Make 


APPENDIX A Macintosh Programmer’s Workshop Files 493 







MakeErrorFile 

Matchlt 

Pascal 

PasMat 

PasRef 

PerformReport 

Print 

ProcNames 

ResEqual 

Rez 

RezDet 

Search 

SetPrivilege 

SetVersion 

Sort 

Translate 

Wherels 
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Appendix B Summary of Selections and 
Regular Expressions 


This appendix formally defines the syntax of selections and regular 
expressions as used in the MPW Shell command language. It also lists the Option- 
key characters used in selections and regular expressions. For examples of their 
use, see Chapter 6. ■ 

Contents 
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Option-key characters 500 
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Selections 

Selections are passed as arguments to the editing commands. They’re defined in 

Table B-l. 

■ Table B-l Selections 

selection (specifies a selection or insertion point) 

§ 

Current selection 

name 

Identifies marked text 

number 

Line number 

! number 

number lines after the end of the current selection 

i number 

number lines before the start of the current selection 

position 

Position (defined below) 

pattern 

Pattern (defined below) 

(. selection ) 

Selection grouping 

selection: selection 

Both selections and everything in between 

position (specifies an insertion point) 

• 

Position before the first character in the file 

oo 

Position after the last character in the file 

A selection 

Position before the first character of selection 

selection A 

Position after the last character of selection 

selection ! number 

Position number characters after the end of selection 

selection j number 

Position number characters before the beginning of 
selection 

pattern (specifies characters to be matched) 

/ entireRegularExpr / 

Regular expression—search forward (see Table B-2) 

\ entireRegularExpr \ 

Regular expression—search backward 

This is the precedence 

/and \ 

( ) 

A 

land i 

• 

• 

of the selection operators, from highest to lowest: 
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Regular expressions 


Regular expressions are used for pattern matching within /.../ and \ ...\. (See “ patterrf in 
Table B-l.) Regular expressions are defined in Table B-2. 

■ Table B-2 Regular expressions 


entireRegularExp r 

•regularExpr 
regularExpr <*> 
regularExpr 

Regular expression at beginning of line 

Regular expression at end of line 

Regular expression 

regularExpr 

simpleExpr 

taggedExpr 

literal 

regularEapr 1 regularExpr 2 

Untagged regular expression 

Tagged regular expression 

Quoted string literal 

regularExpr\ followed by regularExpr 2 

simpleExpr 

(regularExpr) 
characterExpr 
simpleExpr* 
simpleExpr + 
simpleExpr « number » 
simpleExpr « number 
simpleExpr « n,, » 

Regular expression grouping 

Single-character regular expression 

Regular expression zero or more times 

Regular expression one or more times 

Regular expression number times 

Regular expression at least number times 

Regular expression at least n^ times and at most ^ times 

taggedExpr 

( regularExpr)® digit 

The string matched by the regularExpr can be 
referred to as ®digit (where 0 <digit > 9) 

literal 

'string 

"string 1 

Each character in string is taken literally 

Each character in string is taken literally, except for d, 

{}, and substitutions 


(Continued) 
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■ Table B-2 (Continued) Regular expressions 


characterExpr 

character 

Character (unless it’s listed as special in the following table) 

d character 

d defeats special meaning of following character 

7 

Any character except Return 

5=5 

Any string not containing a Return, including the null 
string (this is the same as ?*) 

[ characterList] 

Any character in the list 

[-. characterList] 

Any character not in the list 

characterList 

] 

1” first in list represents itself 

- 

first in list represents itself 

character 

Character 

characterList character 

List of characters 

character , - character 2 

Character range from character , to character 2 inclusive 


♦ Note: The regular expression operators 
? ~ [...] * + «...» 
are also used in filename generation. 


The following characters have special meanings: 


d 

Always special, except within 

? = * + [«()'" 

Special everywhere except within [...],and 


Special only after a right parenthesis character,) 

• 

Special as first character of entire regular expression 

o© 

Special as last character of entire regular expression 

/\ 

Special if used to delimit regular expression 

U 

Special everywhere except within 

i 

Special immediately following left bracket [ 

- 

Special within brackets except immediately following left bracket [ 


The operators are listed below beginning with those with the highest precedence. 

( ) 

?«*+[]«» ® 


concatenation 

• ©o 
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Option-key characters 

The following Option-key characters are used in selections and regular expressions. 

♦ Note: Option-key characters are not case-sensitive. Although upper case letters are 
shown in the text of this reference for readability (the number 1 and lower case L look 
the same), you can use lower case for all Option-letter characters. 


Character 

Key 

Meaning 

§ 

Option-6 

Current selection character 

d 

Option-D 

Escape character 

~ 

Option-X 

Any string 

• 

Option-8 

Beginning of line or file 

oo 

Option-5 

End of line or file 

i 

Option-1 

Minus number of lines or spaces 

A 

Option-J 

Position 

® 

Option-R 

Tag operator 

« 

OptionA 

Encloses number of repetitions 

» 

Option-Shift-\ 

Encloses number of repetitions 

-I 

Option-L 

Character list modifier 
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Appendix C Special Operators 


Here is a brief summary of the special operators used in MPW 3.0. For 
characters that are part of the extended character set, Option-key combinations 
are also given. For details on the action of these operators, see Chapters 5 and 6. 
See Appendix B for a summary of selections and regular expressions. ■ 
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■ Table C*1 MPW operators 


Operator 

Meaning 

Shell character 

space 

tab 

return 

Separates words 

Separates words 

Separates commands 

/ 

1 

Separates commands 

Pipe—separates commands, piping output to input 

&& 

1 1 

“And”—separates commands, executing second if first succeeds 
“Or”—separates commands, executing second if first fails 

{commands) 

# comment 
dchar 
• chars' 

” chars” 

Group commands 

Ignore comment 

Escape—literalizes char; 9n, dt, and 9f are special 0 is Option-D) 

“Hard quotation marks”—literalize chars 
“Soft quotation marks”—literalize chars except for {...} (variable 
substitution),(command substitution), and d (escape) 

/chars/ 

Regular expression quotes—literalize /chars/ except for {...},and d 

... 

Ellipsis (Option-semicolon; not three periods) following a 
command invokes Commando 

\chars\ 

Regular expression quotation marks—literalize \chars\ except for 
{...},and d 

[variably 

'command.' 

Substitute variable 

Substitute output of command 


I/O redirection 

Note: Filename is created if it does not exist 


< filename 

> filename 
» filename 

> filename 
>> filename 

X filename 

Standard input is taken from filename 

Redirect standard output, replacing contents of filename 

Redirect standard output, appending to filename 

Redirect diagnostics, replacing contents of filename (> is Option->) 
Redirect diagnostics, appending to filename (> is Option->) 

Redirect both standard output and diagnostics, 

replacing contents of filename (X is Option-W) 

yy. filename 

Redirect both standard output and diagnostics 
appending to filename (X is Option-W) 


(Continued) 
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■ Table C-l (Continued) MPW operators 


Operator 

Meaning 

Shell numbers 


$[0-9 a-f]+ 

Hexadecimal number 

Ox [0-9 a-f]+ 

Hexadecimal number 

0 [ 0-7 ]+ 

Octal number 

0b [0-1]+ 

Binary number 

Shell operators (by precedence) 

(expr) 

Expression grouping 

- 

(unary) arithmetic negation 

- 

(unary) bitwise negation 

! NOT 

(unary) logical negation (-. is Option-L) 

* 

Multiplication 

- DIV 

Division (-5- is Option-/) 

% MOD 

Modulus 

+ 

Addition 

- 

Subtraction 

« 

Shift left 

» 

Shift right (logical) 

< 

Less than 

<= < 

Less than or equal (< is Option-<) 

> 

Greater than 

>= > 

Greater than or equal (> is Option->) 

== 

Equal 

!* <> * 

Not equal (* is Option-=) 


Equal to a pattern 


Not equal to a pattern 

& 

Bitwise AND 

A 

Bitwise XOR 

1 

Bitwise OR 

&& AND 

Logical AND 

1 1 OR 

Logical OR 
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Appendix D Resource Description Syntax 


This appendix defines the form of resource description files used by the 
MPW 3-0 resource compiler (Rez) and decompiler (DeRez). See Chapter 11 for 
information on how to use these tools. Each tool is defined in detail along with 
examples in Part II. ■ 

Contents 

Syntax notation 507 

Structure of a resource description file 508 

Include—include resources from another file 509 
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Syntax 512 

Preprocessor directives 513 
Syntax 513 
Identifiers 513 
Token delimiters 514 
Compound types 514 
Expressions 514 
Numbers 515 

Variables and functions 516 
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Syntax notation 


The following syntax notation is used in this appendix: 


terminal 
nonterminal 
A | B | C 

{...}? 

{...}+ 


{...}* 

Un 


Must be entered as shown 

May be replaced by anything matching its definition 
Either A or B or C (vertical stacking also indicates an either/or 
choice) 

Enclosed element is optional, but may not be repeated 
Enclosed element may be repeated one or more times (not 
optional) 

Enclosed element may be repeated zero or more times 
Enclosed element must be repeated n times 


If one of the syntax elements must be included literally, it is shown enclosed in single 
quotation marks; for example, 


{ ' {’ data-string '} ’ } ? 

indicates that a data-string is optional, and must be enclosed in braces, if included. 
Otherwise, all punctuation (; , • - $ =) must be entered as shown. 


Note that the ellipsis (three closely spaced periods) within braces signifies only some 
unspecified element on which an operation is to be performed. An actual ellipsis in a 
command line (Option-semicolon) would invoke a command’s Commando dialogs. 

Note that the semicolon is a statement terminator; every statement must be terminated 
by a semicolon. In a resource type definition, semicolons can be liberally sprinkled 
without ill effect. In a resource specification (where the actual resource data is 
initialized), commas are used everywhere to separate items, including array elements. 

The nonterminal symbols used are fully defined under “Syntax” at the end of this 
appendix. 
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Structure of a resource description file 

The MPW resource compiler input file consists of any number of statements, where 
statement may be any of the following: 


include 

Include resources from another file. 

read 

Read the data fork of a file and include it as a resource. 

data 

Specify raw data. 

type 

Declare resource type descriptions for subsequent resource 
statements. 

resource 

Specify data for a resource type declared in a previous type 
statement. 

change 

Change the type, ID, name, or attributes of existing resources. 

delete 

Delete existing resources. 
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Indude—indude resources from another file 

include file { include-selector }? ; 


include-selector :■= 

resource-^} ‘ (’ ID-specifier‘) ’}? 
not resource-type 
resource-typel as resource-type2 
resource-typel ‘ (’ ID-specifier 1 ) ’ 

a s resource-type2 ' (’ resource-specifier ‘) ’ 

file ::= 

ID-specifier ::= 

string 

ID-range 

resource-name 

ID-range ::= 
resource-specifier ::= 

resource-ID ::= 

mum 

resource-ID {, rESOwrce-rfcwt#}? { resource-attributes }? 
word-expression 

resource-name ::= 

string 

resource-attributes ::= 

{resource-literal-attributes}* 1 resource-numeric-attributes 

resource-numeric-attributes ::= 

,byte-expression 

resource-literal-attributes ::= 

{, sysheap 1 , appheap }? 

{ t purgeable 1 , nonpurgeable }? 


{ flocked I ,unlocked}? 

{ , preload I , nonpreload}? 


Read—read data as a resource 

read resource-type ‘ <’ resource-specifier ‘)’file ; 


Data—specify raw data 

data resource-type' C resource-specifier‘)’ ‘data-slring {;}?'}’ ; 
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Type—declare resource type 


type resource-type{ ‘( ’ID-range V}? ‘ {’ ({label':’} * type-statement ;} * '}’ 
resource-type ::= long-expression 


type-statement ::= 

data-type 

fill-type 

alignment 

switch-type 

array-type 

label 

identifier 


Datatype 

data-type ::= data-type-specifier{ symbolic-declaration I = declaration-constant }? 


data-type-specifier 

char 

string {‘ [’ length 1 ] ’}? 
pstring {‘ [* length 1 ] 1 }? 
cstring {‘ [’ length ‘] *}? 
wstring {*[’ length T }? 
numeric-type-specifier 
point 

rect 

length ::= 

numeric-type-specifier :■= 

expression 

boolean 

{ unsigned}? {rarfix}? numeric-type 

radix ::= 

binary 

octal 

decimal 

hex 

literal 

numeric-type ::= 

byte 

integer 

longint 

bitstring 1 [’ *] * 

symbolic-declaration ::= 

range-block{, range-block}* 
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declaration-constant ::= 

expression 

point-constant 

rect-constant 

string 

Fill-type 

fill-type ::= 
fill-size ::= 

fill fill-size {‘ [’ expression ‘] ’}? 
bit 1 nibble 1 byte 1 word 1 long 

Alignment 

alignment ::= 
align-size ::= 

align align-size 

nibble 1 byte 1 word 1 long 

Switch-type 

switch-type 
switch-body ::= 

swit ch ‘ { ’switch-body '} ’ 

{case case-name : case-body }+ 

case-name ::= 

identifier 

case-body ::= 

key-constant-statement ::= 

{ type-statement ; }* key-constant-statement ; { type-statement ; }* 
key data-type-specijier = declaration-constant 

Array-type 

array-type ::= 

array-specifier 

{wide}? array { array-specifier}ltype-body 

array-name 

1 [’expression!] ’ 

array-name ::= 

type-body ::= 

identifier 

'{’{type-statement ;}* 


APPENDIX D Resource Description Syntax 511 




Resource—specify resource data 


re source resource-type ‘ (’ resource-specifier ‘) ’ data-body ; 
data-body ‘ {’ { data-statement {, daia-statemeni }*}?'}’ 


data-statement ::= 


switch-data ::= 
array-data ::= 

array-element ::= 


expression 

point-constant 

rect-constant 

string 

identifier 

switch-data 

array-data 

case-name data-body 
V( array-element {, array-element }*}?'}’ 

{ data-statement {, data-statement }*}? 


Change—change resource vital information 

change resource-type {'(’ ID-specifierJ }? to resource-type2‘C resource-specifier J ; 

Delete—delete resource(s) 

delete resource-type {'(’ ID-specifierJ }?; 


Labels 

labels support some of the more complicated resources such as • nfnt • and color 
QuickDraw resources. Use labels within a resource type declaration to calculate offsets 
and permit accessing of data at the labels. 


Syntax 

label ::= character {alphanum}* *:* 

character I A | B I C _ 

number ::= 0|lj2|3|4|5J6!7|8|9 

alphanum character I number 
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Preprocessor directives 

These preprocessor directives are available: 

♦define identifier{define-string }? 

#undef identifier 
#if preprocessor-expr 
#elif preprocessor-expr 
♦else 
♦endif 

♦ifdef identifier 
♦ifndef identifier 

♦print f ( string {, [ expression I string ]} *) 

Preprocessor-expr is the same as expression with the following additional expressions: 

defined ‘(’ identifier 1 )' 
defined identifier 


Syntax 

This section defines the nonterminal symbols used in the previous sections. 


Identifiers 

■ An identifier may consist of letters (A-Z, a-z), digits (0-9), or the underscore 
character ( _ ). 

■ Identifiers may not start with a digit; otherwise any mix of letters, digits, and 
underscores is acceptable. 

■ Identifiers are not case sensitive. 

■ An identifier may be of any length. 
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Token delimiters 


token-delimiter :■= 
comment w- 


Compound types 

point-constant 
rect-constant ::= 


Expressions 

bit-expression ::= 
byte-expression ::= 
word-expression ::= 
long-expression ::= 

expression ::= 


[space I tob I newline I comment }+ 

7*’ { printing-character}* **/’ 

// { printing-character}* newline 


‘{'expression, expression V 

‘{’expression, expression, expression, expression '} 


expression 

expression 

expression 

expression 

integer-constant 

literal-constant 

numeric-variable 

system-function 

expression 

label 

- expression 
~expression 
! expression 


‘C expression O’ 
expression » 

expression 

expression 

« 

expression 

expression 

A 

expression 

expression 

*i r 

expression 

expression 

&& 

expression 

expression 


expression 

expression 

& 

expression 

expression 

! = 

expression 

expression 

== 

expression 

expression 

>= 

expression 

expression 

<= 

expression 
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system-function ::= 


expression 

expression 

expression 

expression 

expression 

expression 

expression 


> expression 

< expression 

expression 
+ expression 

* expression 

/ expression 

% expression 


$$countof ‘ (’ array-name ‘) ’ 

$$packedsize ‘(’ StartOffSet, RowBytes, RowCount ')’ 


Numbers 

integer-constant ::= 


decimal-constant ::= 
octal-constant 
hexadecimal-constant 
binary-constant ::= 

decimal-marker ::= 
hex-marker ::= 
binary-marker :■= 

octal-digit :•= 
hex-digit ::= 


binary-digit ::= 
literal-constant ::= 


decimal-constant 

octal-constant 

binary-constant 

hexadecimal-constant 

nonzero-digit {}* 

0{ octal-digit}* 
hex-marker {hex-digit }+ 
binary-marker { binary-digit}+ 

Od I od 
O x I ox I $ 

Ob I OB 

0 I 1 I 2 I 3 I 4 I 5 I 6 I 7 
0lll2l3l4l5l6l7l8l9l 
aIbIcIdIeIfI 
a I b I c I d I e I f 
0 I 1 

* { character}* • 
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Variables and functions 


string-variable 

$$Version 

$$Date 

$$Time 

$$Name 

$$sheii‘ (’" Shell-variable- name” ') ’ 

$$Resource‘ (’ file, resource-id, resourceName-or-IU) ’ 

$$Format ( stringi, [ expression 1 string ]} *) 

resourceName-or-ID ::= resource-id 

resource-name 

numeric-variable 

$$Hour 

$$Minute 

$$ Second 

$$Year 

$$Month 

$$Day 

SSWeekday 

$$Type 

$$ID 

SSAttributes 

$$ResourceSize 

$$BitField ( expression, expression, expression ) 
SSByte ( expression ) 

$$Long ( expression ) 

$$PackedSize (.expression, expression, expression ) 
$$Word ( expression) 
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Strings 

string ::= 

simple-string :■= 
hex-string ::= 
character ::= 
escape-character ::= 
escape-code ::= 
character-escape-code ::= 
numeric-escape-code ::= 


simple-string 
hex-string 
string-variable 
string string 

” { character}* n 

$ " { hex-digit hex-digit }* " 

printing-character I escape-character 

\ escape-code 

character-escape-code I numeric-escape-code 

nltlblrlflvl?l\l'I" 

{ octal-digit }3 

decimal-marker { decimal-digit }3 
hex-marker {hex-digit }2 
binary-marker {binary-digit }8 
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Appendix E File Types, Creators, and Suffixes 


Contents 

File types and creators 521 
File suffixes 521 
Text files 522 
Object files 522 
Data files 522 






File types and creators 

Table E-l lists MPW file types and creators. 


♦ Note: The file type ' ob j • actually contains a space before the closing single 
quotation mark. Likewise, the creator 'mps ' has a space before its closing 
quotation mark. 


■ Table E-l File types and creators 


File 

Type 

Creator 

MPW Shell 

'APPL' 

•mps * (MPSspace) 

Tools 

'MPST' 

'MPS ' 

Text files 

'TEXT' 

•MPS ' 

Object files 

'OBJ • 

'MPS ' 

Assembler load/dump 

•DMPA' 

'MPS ' 

C load/dump 

'DMPC* 

'MPS ' 

Pascal load/dump 

•dmpp* 

'MPS ' 

ProjectorDB 

'MPSP' 

•MPS ' 

SADE 

'APPL' 

'sade 1 

SADE text files 

'TEXT' 

1 sade 1 

SADE symbol files 

'MPSY' 

•sade* 

SADE symbol files 

. sym 

'sade* 


File suffixes 

The following sections define file suffix conventions. 


APPENDIX E File Types, Creators, and Suffixes 521 








Text files 


name, a 

Assembly-language source file 

name.z.\sx 

Assembler listing file 

name, c 

C or C++ source file 

name, cp 

C++ source file 

name, h 

C header file 

name, map 

Linker map 

name, p 

Pascal source file 

names 

Resource description file (resource compiler (Rez) input) 


Text files are identified by their file type (* text •) rather than by a special suffix. Several 
applications (including MacWrite, MDS Edit, and the MPW Shell) can create and edit files 
of type • text •. The creator » mps • indicates to the Finder that the MPW Shell is the 
application to launch when a text file is opened. 


Object files 

name.a.o Object file created by the assembler 

name.p.o Object file created by the MPW Pascal Compiler 

name. c.o Object file created by the MPW C Compiler 

name.o Object file (library) created by Lib; object files shipped with MPW 

Compilers add the suffix “.o” to the source file name to construct the object file name. 
The language suffix is left in the name in order to prevent name conflicts for programs 
whose components are written in several languages. (For example, a program might have 
source files MacGismo.a and MacGismo.c and object files MacGismo.a.o and 
MacGismo.c.o.) 


Datafiles 

ProjectorDB Database file created by Projector 
name.SYM Symbolic information file created by the linker 

The linker adds the suffex “.SYM” to the output filename in response to the -sym option. 
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Appendix F Tools Libraries 


The mpw Tools Library, found in ToolLibs.o, includes procedures and 

HEADER FILES to 

■ control the MPW rotating beach ball cursor 

■ retrieve the text of Macintosh Operating System error messages 
from the MPW error message file 

■ dissassemble MC68xxx machine code 

MPW Assembly language programmers can use either MPW Pascal or MPW C calls 

to all of these routines. Therefore, only the Pascal and C calling conventions are 

shown here. (However, you will find special notes for Assembler users.) ■ 

Contents 

Animated cursor control routines 525 

Cursor control routines—MPW Pascal 525 
Cursor control routines—MPW C 525 
The InitCursorCtl procedure 526 
The Show_Cursor procedure 527 
The Hide_Cursor procedure 528 
The RotateCursor procedure 529 
The SpinCursor procedure 529 

Error Message File manager 530 
Error Manager—MPW Pascal 530 
Error Manager—MPW C 530 
The InitErrMgr procedure 531 
The GetSysErrText procedure 532 
The GetToolErrText procedure 533 
The AddErrlnsert procedure 534 
The CloseErrMgr function 534 


523 



Disassembler Lookup routines 535 
DisAsmLookUp.p—MPW Pascal 535 
DisAsmLookUp.h—MPW C 535 
Using the Disassembler 536 
The InitLookup procedure 541 
The Lookup procedure 542 
The LookupTrapName procedure 542 
The ModifyOperand procedure 543 
The validMacsBugSymbol function 543 
The endOfModule function 545 
The showMacsBugSymbol function 545 


524 
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Animated cursor control routines 


Five procedures in the MPW Tools Library let you control the appearance'and action of 
the MPW cursor. The rotating beach ball cursor says “I am currently processing.” These 
routines all use Pascal calling conventions and Pascal-style strings. 


♦ Note: Spinning the cursor allows your tool to operate in the background under 
MultiFinder. 


Cursor control routines—MPW Pascal 

To access the cursor control unit in MPW Pascal, do the following: 

■ Include these statements in your source text: 

USES { $U MemTypes. p} MemTypes, 

{$U CursorCtl.p} CursorCtl; 

The uses clause and the $u compiler directive are described in the MPW3-0 Pascal 
Reference. 

■ Link your compilation with the file ToolLibs.o. 


Cursor control routines—MPW C 

The MPW C header file CursoiCtl.h provides interfaces to procedures in the MPW Tools 
Library that let you control the appearance and action of the cursor. link this file with the 
file ToolLibs.o. 

To access the cursor control unit in MPW C, include this statement in your source text 

#include <CursorCtl.h> 
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The InitCursorCtI procedure 

The initcursorcti procedure initializes the cursorcti unit. Call this procedure once 
prior to calling the RotateCursor or spinCursor procedures described later in this 
appendix. Note that initcursorcti doesn’t need to be called if you use only 
Hide_Cursor and Show_Cursor. 

If the parameter NewCursorsis nil, initcursorcti loads in the 'acur' resource and 
the ’ curs ' resources specified by the * acur 1 resource ID. If any of the resources 
cannot be loaded, the cursor will not be changed. The 'acur 1 resource is assumed to be 
either in the currently running tool or application or the MPW 3.0 Shell for a tool or in the 
System file. The • acur • resource ID must be 0 for a tool or application, 1 for the Shell, 
and 2 for the System file (assuming that cursors are in the System file). 

If NewCursors is not nil, it is assumed to be a handle to an 1 acur ' -formatted resource 
designated by the caller and uses it instead of executing the GetResource procedure on 
'acur'. 


♦ Note: If you call RotateCursor or SpinCursor without first railin g 

InitCursorCtl , then RotateCursor and SpinCursor do the work of 
initcursor the first time you make the call. However, it is preferable to all 
initcursorcti first because of one possible disadvantage: The resource memory 
alloated may ause fragmentation to occur in the appliation. Calling 
initcursorcti has the advantage of alloating memory at a time you specify. 


cursorcti declares acurHandie as a handle to ' acur ' resources of type record as 
follows: 


TYPE 


acurHandie = A acurPtr; 
acurPtr = A acur; 

{Handles to 'acur' resources} 

{Pointers to 'acur' resources} 

acur 

N: 

Index: 
Framel: 
filll: 
Frame2: 
fill2: 

RECORD 

integer; 

integer 

integer 

integer 

integer 

integer 

{Layout of an 'acur' resource} 

{Number of cursors ("frames of film")} 
{Next frame, to show <for internal use>} 
{'CURS' resource ID - frame #1} 

{<for internal use>} 

{'CURS' resource ID - frame #2} 

{<for internal use>} 

{'CURS * resource ID - frame #2} 

{{<for internal use>} 


FrameN: 
fillN: 

integer 

integer 


END; 
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See "The RotateCursor Procedure” for a description of how the • acur • frames are used 
to animate the cursor. 

A Warning initcursorcti modifies the 'acur* resource in memory. 

Specifically, it changes each FrameN/fillN integer pair to a han dle to 
the corresponding * curs • resource also in memory. Thus if 
Newcursors is not NULL when initcursorcti is called, you must 
guarantee that NewCursors always points to a “fresh” copy of an 
' acur 1 resource. This need concern you only if you want to 
repeatedly use multiple * acur' resources during execution 
of your tools. ▲ 


MFW Pascal 

InitCursorCtl(NewCursors: UNIV acurHandle); 


MFW C 

pascal void InitCursorCtl(acurHandle newcursors); 


The Show Cursor procedure 

The Show_cursor procedure increments the cursor level (which may have been 
decremented by Hide_Cursor). If the level is zero, it displays the cursor. The cursor 
level never increments above zero. The parameter CursorKind lets you select the form of 
the cursor: 


■ Table F-l Cursor kinds 


Value 

Cursor 

0 

Hidden cursor 

1 

I-beam 

2 

Cross 

3 

Plus sign 

4 

Watch 

5 

Arrow 
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Except for hidden_cursor, a Macintosh setcursor is done for the specified cursor 
prior to doing a showCursor. hidden_cursor simply causes a Showcursor call. 

♦ Note: intiGraf ( ) must be called before any calls to Showcursor 

(arrow_cursor) because the arrow cursor is one of the QuickDraw globals set up by 
IntiGraf( ). 


MPW Pascal 

Show_Cursor(CursorKind: Cursors); 
cursorcti declares the type cursors as follows: 

TYPE 

Cursors = (HIDDEN_CURSOR, I_BEAM_CURSOR, CROSS_CURSOR, 
PLUS_CURSOR, WATCH_CURSOR, ARROW_CURSOR); 


MPW C 

pascal void Show_Cursor(Cursors cursorKind); 


The Hlde_Cursor procedure 

The Hide_cursor procedure caOs the Macintosh HideCursor routine. (Thus the 
Macintosh cursor level is decremented by 1 when this routine is called.) If the cursor was 
visible, it is then hidden. For further information, see the chapter “QuickDraw” of Inside 
Macintosh. 

MPW Pascal 

Hide Cursor; 


MPW C 

pascal void Hide_Cursor (void) 


528 MPW 3.0 Reference 





The RotateCursor procedure 

The RotateCursor procedure rotates the beach ball cursor (or animates whichever 
sequence of cursors has been set by the user in an * acur • resource and loaded with 
initcursorcti) and rotates it one-quarter turn (that is, advances to the next • acur * 
resource frame) whenever the value of Counter is a multiple of 32. To use 
RotateCursor, your program must set up and increment (or decrement) a suitable 
counter. If the value of Counter is positive, the cursor rotates clockwise (that is, 
sequencing is forward through the 'acur 1 cursor frames); if it is negative, it rotates 
counterclockwise (that is, sequencing is backward circularly through the ' acur * resource 
frames). 

♦ Note: RotateCursor invokes a Macintosh Setcursor call for the proper cursor 
picture. It assumes that the cursor is visible as the result of a prior show_cursor call. 


MPW Pascal 

RotateCursor(Counter: longint); 


MPW C 

pascal void RotateCursor(long counter); 


The SplnCursor procedure 

The SpinCursor procedure performs the same actions as RotateCursor, but 
maintains its own internal counter rather than passing a counter. It is provided for those 
who do not have a convenient counter handy but still want to use the spinning beach ball 
cursor or any sequence of cursors specified by initcursorcti. Your program specifies 
the Increment to be counted (either positive or negative), and SpinCursor adds it to 
its counter. A positive increment spins the cursor clockwise (that is, sequencing is forward 
through the ' acur • cursor frames); a negative increment spins it counterclockwise (that 
is, sequencing is backward circularly through the • acur ' resource frames). An Increment 
value of zero resets the counter to zero. 

♦ Note: It is the sign of the increment, not the sign of the accumulated value of the 
SpinCursor counter, that determines the cursor’s direction of spin. 
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MFW Pascal 


SpinCursor(Increment: integer); 


MPWC 

pascal void SpinCursor(short increment); 


Error Message File manager 

Four procedures in the MPW Tools Library let you retrieve the text of error messages in the 
Macintosh Operating System error message file or in an error file private to a tool (created 
with the MakeErrorFile tool). 


Error Manager—MPW Pascal 

To use the error message file manager in MPW Pascal, do the following: 

■ Include the statement 

USES {$U MemTypes.pl MemTypes, {$U ErrMgr.p} ErrMgr; 

in your source text. The uses clause and the $u compiler directive ate described in 
the MPW 3.0 Pascal Reference. 

■ link your compilation with the file ToolLibs.o. 

Error Manager—MFW C 

Use the header file ErrMgr.h which includes the file Types.h. Link this file with ToolLibs.o. 
♦include <ErrMgr.h> 
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The InitErrMgr procedure 


The InitErrMgr procedure must be called before any of the other error mess age file 
manager procedures. To access Macintosh Operating System error messages, use the 
Pascal call 

InitErrMgr(", ", false) ; 

This call causes the error manager to access the file SysErr.Err in the directory 
{ShellDirectory} if that Shell variable is defined; otherwise, it will use file SysErr.Err. 

If InitErrMgr is not explidfiy called, then GetSysErrText or GetToolErrText will 
call InitErrMgr (• •, ", true) the first time they are caUed 

If you wish to access a tool-specific error file, supply the name of the error file as the first 
parameter to InitErrMgr. If the tool is an MPW tool with the error file copied into the 
tool’s data fork, the first parameter may be the null string and the ErrMgr will open the 
appropriate file. This occurs only if CRuntime.o or PasLib.o is linked with the program. 

Set ShowToolErrNbrs to TRUE if you want all messages to begin with the error number, as 
in 

<msgtxt> ([OS]Error<n>) 

Failure by the Error Manager to find the message text always results in a message of this 
form (without the <msgtxt>). TooiErrFileName is used to specify the name of the 
tool-specific error file, and should be the null string if not used (or if the tool’s data fork is 
to be used as the error file). Use sysErrFileName to specify the name of the system 
error file. This should normally be the null string which causes the Error Manager to look in 
the MPW Shell directory for “SysErrs.Err”. Specifying names for the error files avoids 
intEnv calls that look up the values of Shell variables. 


MPW Pascal 

PROCEDURE InitErrMgr(toolErrFilename: Str255;sysErrFilename: 
Str255;ShowToolErrNbrs: BOOLEAN); 


MPW C 

InitErrMgr(Str255 toolErrFilename,Str255 sysErrFilename, 
Boolean ShowToolErrNbrs); 
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♦ Note: The Assembler caller must define and export the variable _EnvP with a null value 
if CRuntime.o or Paslib.o is not linked with the tool. For example, outside all 
modules (procs) place the following: 

EXPORT _EnvP 

EnvP DC. L 0 


The GetSysErrText procedure 

The GetSysErrText procedure fetches the message text that corresponds to the 
system error number value of MsgNbr. ErrMsg is a pointer to a string of type st r 2 55 , in 
which the error message text will be placed. The maximum length of the message is limited 
to 254 characters. 

If GetSysErrText is successful (and if showTooiErrNbrs is true on the init call), the 
form of the error message returned is 

error text (OS error number) 

If it is unsuccessful, the form of the error message returned is 
05 error number (reason message not found) 

Possible reasons for unsuccessful execution of GetSysErrText are that the file 
SysEmErr was not found or that it contained no message text corresponding to MsgNbr. 

♦ Note: If a system message filename was not specified to initErrMgr, then the error 
manager assumes the message file contained in the file SysErrs.Err. This file is first 
accessed as {ShellDirectory}SysErrs.Err on the assumption that SysErrs.Err is kept in 
the same directory as the MPW Shell. If the file cannot be opened, then the error 
manager attempts to open SysErrs.Err in the System Folder. 


MPW Pascal 

PROCEDURE GetSysErrText(msgNbr: INTEGER;errMsg: StringPtr); 
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MFWC 


void GetSysErrText(short msgNbr,char *errMsg); 

Get error message text corresponds to the error number msgNbr from the system error 
message file (“SysErrs.Err” in {ShellDirectory}). The text of the message is returned in 

errMsg. 


The GetToolErrText procedure 

The GetTooiErrText procedure fetches the message text that corresponds to the tool 
error message file error number msgNbr. (The tool error filename is specified in the 
initErrMgr call.) The text message is returned in errMsg. 

Inserts are indicated in error messages by specifying a “A” (Up Arrow) to indicate where 
the insert is to be placed. Any message to be inserted should be contained in errinsert. 
Otherwise, errinser should be null. The error insert is placed in the text of the error 
message replacing the first instance of the “A” character in the message; if no, “a* is 
present, the error insert is appended to the end of the text of the message following an 
intervening blank. 

♦ Note: If a tool message filename was not specified to initErrMgr, then the error 
manager assumes the message file contained in the data fork of the tool calling the 
error manager. This name is contained in the Shell variable {Command} and the value of 
that variable is used to open the error message file. 


MPW Pascal 

PROCEDURE GetTooiErrText(msgNbr: INTEGER;errinsert: Str255;errMsg: 
StringPtr); 


MPW C 

void GetTooiErrText(short msgNbr,char *errlnsert,char *errMsg); 
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The AddErrlnsert procedure 

The AddErrlnsert procedure adds another insert to an error message string. This call 
may be used when more than one insert is needed in a message (because it contains more 
than one “ A ” character). The insert is handled in the same fashion as in the 
GetToolErrText call. 


MPW Pascal 

PROCEDURE AddErrlnsert(insert: Str255;msgString: StringPtr); C; 

MPWC 

void AddErrlnsert(unsigned char ^insert,unsigned char *msgString); 


The CloseErrMgr function 

Ideally you should call CloseErrMgr at the end of execution to make sure all files 
opened by the error manager are closed. You can let normal program termination do the 
closing. 


MPW Pascal 

PROCEDURE CloseErrMgr; C; 


MPW C 

void CloseErrMgr(void); 
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Disassembler Lookup routines 

The Disassembler Lookup is an interface (available in MPW Pascal and MPW C) to the 
Macintosh libraries. It is a Pascal routine that disassembles a sequence of bytes. 

All MC68xxx family instructions are supported, including MC68881, MC68882, and 
MC68851 instructions. The sequence of bytes to be disassembled are pointed to by 
FirstByte. BytesUsed bytes starting at FirstByte are consumed by the 
disassembly, and the Opcode, Operand, and Comment strings returned as NULL 
TERMINATED Pascal strings (for easier manipulation with C). You are then free to format 
or use the output strings in any way appropriate to the application. 

The Pascal interface file DisAsmLookUp.p is located in the PInterfaces folder. The C 
interface file, DisAsmLookUp.h, is located in the CInterfaces folder. A discussion of each 
of these interface files and a general explanation of the Disassembler follows. 


DisAsmLookUp.p—MPW Pascal 

TYPE 

LookupRegs = 

L. A0 _' _ A1 _/ _ A2 _f _ A3 _f _A4_, _A5_, _A6_, _A7_, _PC_, _ABS_, _TRAP_) ; 
DisAsmStr80 = String[80]; 


PROCEDURE Disassembler(DstAdjust: LONGINT;VAR BytesUsed: 
INTEGER; 

FirstByte: UNIV Ptr; VAR Opcode: UNIV DisAsmStr80; 
VAR Operand: UNIV DisAsmStr80;VAR Comment: UNIV 

DisAsmStr80; 

LookUpProc: UNIV Ptr); 


DisAsmLookUp.h—MPW C 

enum {_A0_, _A1_, _A2_, _A3_, _A4_, _A5_, _A6_, _A7_, _PC_, _ABS_, _TRAP_} ; 
typedef unsigned char LookupRegs; 

pascal void Disassembler(long DstAdjust,short ‘BytesUsed,Ptr FirstByte, 
char *Opcode,char ‘Operand,char ‘Comment,Ptr LookUpProc); 
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Using the Disassembler 

Depending on the opcode and effective addresses (EA’s) to be disassembled, the 
Opcode, Operand, and Comment strings contain the following information: 


■ Table F-2 Disassembler strings 


Case 

Opcode 

Operand 

Comment 

Non PC-relative EA’s 

op.sz 

EA’s 


PC-relative EA’s 

op.sz 

EA’s 

; address 

Toolbox traps 

DC.W 

$AXXX 

; TBXXXX 

OS traps 

DC.W 

$AXXX 

; OSXXXX 

Invalid bytes 

DC.W 

$XXXX 

• ???? 

Invalid byte #immediate 

DC.W 

$XXXX,... 

; op.SZ #$??XX,EA 


For valid disassembly of processor instructions, Disassembler generates the appropriate 
MC68xxx opcode mnemonic for the Opcode string along with a size attribute when 
required. The source and destination EA’s are generated as the Operand along with a 
possible comment Comments start with a semicolon (;). Traps use a DC.W assembler 
directive as the Opcode, the trap word as the Operand, and a comment indicating the 
trap number and whether the trap is a toolbox or OS trap. As described later in this 
appendix, you can generate symbolic substitutions into EA’s and provide names for traps. 

Invalid instructions cause the string • dc . w • to be returned in the Opcode string. 

Operand is • $xxxx * (the invalid word) with a comment of????. 

Bytesused is 2. This is similar to the trap call case except for the comment. 

A special case is made for immediate byte operands with a nonzero high-order byte. For 
example, the bytes $02001 iff, when actually executed, are interpreted as 

ANDI.B $FF,D0. 

The processor will ignore the high-order byte of the immediate data! Thus, the bytes may 
be considered as valid. Because the Disassembler has no way of knowing the context in 
which it is disassembling, it returns the Opcode as ' dc . w • as in the normal invalid case. 
However, the Operand string shows all the words disassembled separated with commas, 
and it places the possibly valid disassembly in the Operand’s comment indicating the 
nonzero bytes. Thus, for the example $020011FF bytes, the Opcode will be ' dc . w ', the 
Operand will be '$0200,$1 IFF*, and the CommentANDI.B #$??FF,D0'. Bytesused in this 
case would be 4. 
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♦ Note: the Operand EA’s are syntactically similar to but not compatible with the MPW 
Assembler? This is because the Disassemblergenerates byte hex constants as "$XX" 
and word hex constants as "$XXXX\ Negative values (such as $FF or $FFFF) produced 
by the Disassembler are treated as long word values by the MPW Assembler. Thus it is 
assumed that Disassembler output will not be used as MPW Assembler input. If that is 
the goal, you must convert strings of the form $XX or $XXXX in the Operand string to 
their decimal equivalent. 


The routine Modif yoperand is provided in the Disassembler routine to aid with the 
conversion process. 

Since a PC-relative comment is an address, the only address that the Disassembler knows 
about is the address of the code pointed to by FirstByte. Generally, that may be a 
buffer that has no relation to “reality,” that is, the actual code loaded into the buffer. 
Therefore, to allow the address comment to be mapped back to some actual address, you 
may specify an adjustment factor, specified by DstAd just, that is added to the value 
that normally would be placed in the comment 

The Disassembler generates operand-effective address strings as a function of the 
effective address mode. A special case is made for A-trap opcode strings. In places where 
a possible symbolic reference could be substituted for an address (or a portion of an 
address), the Disassembler can call a user-specified routine to do the substitution (using 
the LookupProc parameter described later). The following table summarizes the 
generated effective addresses and notes where symbolic substitutions (S) can be made: 
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Table F-3 Disassembler: Effective addresses 


Mode Generated Effective Address Effective Address with Substitution 


0 

Dn 

Dn 

1 

An 

An 

2 

(An) 

(An) 

3 

(An)+ 

(An)+ 

4 

<An) 

-(An) 

5 

9(An) 

S(An) or just S (if An=A5,9^0) 

6n 

9(An,Xn.Size*Scale) 

S(An,Xn.Size*Scale) 

6n 

(BD,An,Xn.Size*Scale) 

(S,An,Xn.Size*Scale) 

6n 

([BD,An],Xm.Size*Scale,OD) 

([S,An],Xm.Size*Scale,OD) 

6n 

([BD,An,Xn.Size*Scale],OD) 

([S,An,Xn.Size*Scale],OD) 

70 

d 

S 

71 

9 

S 

72 

*±9 

S 

73 

*±9(Xn.Size*Scale) 

S(Xn.Size*Scale) 

73 

(*±9,Xn.Size*Scale) 

(S,Xn.Size*Scale) 

73 

(l*±9],Xm.Size*Scale,OD) 

([S],Xm. Size*Scale,OD) 

73 

([*±9,Xn.Size*ScaIe],OD) 

([S,Xn.Size*Scale],OD) 

74 

#data 

#data 


For A-traps, you can substitute for the DC.W opcode string. If the substitution is made, 
the Disassembler will generate ,sys and/or ,immed flags as operands for Toolbox traps 
and AutoPop for OS traps when the bits in the trap word indicate these settings. 



Generated 

Substituted 



Opcode Operand Comment 

Opcode 

Operand 

Comment 

Toolbox 

DC.W $AXXX ; TBXXXX 

S 

[,Sys][,Immed] 

; AXXX 

OS 

DC.W $AXXX : OSXXXX 

S 

L AutoPop] 

; AXXX 


All displacements (9, BD, OD) are hexadecimal values shown as a byte ($XX), word 
($XXXX), or long ($XXXXXXXX) as appropriate. The *Scale is suppressed if it is 1. The Size 
is W or L Note that effective address substitutions can only be made for “d(An)”, 
“BD.An”, and **±9” cases. 

For all the effective address modes 5,6n, 7n, and for A-traps, a coroutine (a procedure) 
whose address is specified by the LookupProc parameter is called by the Disassembler 
(if LookupProc is not NIL) to do the substitution (or A-trap comment) with a string 
returned by the procedure. It is assumed that the procedure pointed to by LookupProc 
is a level 1 Pascal procedure declared as follows: 
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PROCEDURE Lookup( PC:UNIV Ptr; 

BaseReg: LookupRegs; 

'Opnd:UNIV Longlnt; 

VAR S: DisAsmStr80) ; 

where TYPE D is 
AsmStr80 = String[80]; 
orinC, 

pascal void Lookup(Ptr 

LookupRegs 
long 
char 

These values are explained here: 

PC PC means pointer to instruction extension word or A-trap word 

in the buffer pointed to by the Disassembler's FirstByte 
parameter. 

BaseReg BaseReg determines the meaning of the opnd value and 

supplies the base register for the “9(An)”, “BD,An”, and “*±9” 
cases. 

BaseReg may contain any one of the following values: 

■ Table F-4 Base register values 


AO 

= 0 ==> AO 

A1 

= 1 ==>A1 

A2 

= 2 ==> A2 

_A3_ 

= 3==>A3 

A4 

= 4 ==> A4 

_A5_ 

= 5==>A5 

A6 

= 6 ==> a6 

_A7_ 

= 7 ==> A7 

PC 

= 8 ==> PC-relative (special case) 

_ABS_ 

= 9 ==> Abs addr (special case) 

_TRAP_ 

= 10 ==> Trap word (special case) 


For absolute addressing (modes 70 and 71), BaseReg contains _abs_. 
For A-traps, BaseReg would contain _trap_. 


PC, 

BaseReg, 

Opnd, 

*S); 


{Addr of extension/trap word} 
{Base register/lookup mode } 
{Trap word, PC addr, disp. } 
{Returned substitution } 
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Opnd The contents of this Longint is determined by the BaseReg parameter 

just described. 

For BaseReg = _TRAP_ (A-traps) 

Opnd is the entire trap word. The high-order 16 bits of 
opnd are zero. 

For BaseReg = _ABS_ (absolute effective address) 

opnd contains the (extended) 32-bit address specified by 
the instruction's effective address. Such addresses are 
generally used to reference low-memory globals on a 
Macintosh. 

For BaseReg = _PC_ (PC-relative effective address) 

opnd contains the 32-bit address represented by “*±9” 
adjusted by the Disassembler's DstAd just parameter. 

For BaseReg = _An_ (effective address with a base register) 

opnd contains the (sign-extended) 32-bit (base) 
displacement from the instruction’s effective address. 


In the Macintosh environment, a BaseReg specifying A5 implies either global 
data references or Jump Table references. Positive opnd values with an A5 
BaseReg thus mean Jump Table references, while a negative offset would mean a 
global data reference. Base registers of A6 or A7 would usually mean local data. 

S S is a Pascal string returned from Lookup containing the effective 

address substitution string or a trap name for A-traps. S is set to null prior 
to calling Lookup. If it is still null on return, the string is not used. If not 
null, then for A-traps, the returned string is used as a opcode string. In all 
other cases the string is substituted as shown in the above table. 
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Depending on the application, you have three choices on how to use the Disassembler and 
an associated Lookup procedure: 

1. You can call just the Disassembler and provide your own Lookup procedure. In that 
case, you must follow the calling conventions discussed above. 

2. You can provide MI for the LookupProc parameter, in which case, no Lookup proc 
will be called. 

3. You can first call initLookup (described later in this appendix, a procedure 
provided with this unit) and pass the address of this unit’s standard Lookup 
procedure when Disassembler is called. In this case, all the control logic to determine 
the kind of substitution to be done is provided for you and all that you need to 
provide are the routines to look up any or all of the following: 

■ PC-relative references 

■ Jump table references 

■ Absolute address references 

■ Trap names 

■ References with offsets from base registers 

The InitLookup procedure 

PROCEDURE InitLookup(PCRelProc: UNIV Ptr;JTOffProc: UNIV Ptr; 

TrapProc: UNIV Ptr; AbsAddrProc: UNIV Ptr;IdProc: UNIV Ptr); 

This procedure prepares for use of this unit’s Lookup procedure. When the Disassembler 
is called and the address of this unit’s Lookup procedure is specified, then for PC- 
relative, jump table references, A-traps, absolute addresses, and offsets from a base 
register, the associated level 1 Pascal procedure specified here is called (if it is not 
NULL—all five addresses are preset to NULL). The calls assume the following declarations 
for these procedures (see “Lookup” later in this appendix for further details): 

PROCEDURE PCRelProc(Address: UNIV Longlnt; 

VAR S: UNIV DisAsmStr80) ; 

PROCEDURE JTOffProc(A5JTOffset: UNIV Integer; 

VAR S: UNIV DisAsmStr80) ; 

PROCEDURE TrapNameProc(TrapWord: UNIV Integer; 

VAR S: UNIV DisAsmStr80); 

PROCEDURE AbsAddrProc(AbsAddr: UNIV Longlnt; 

VAR S: UNIV DisAsmStr80); 
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PROCEDURE IdProc(BaseReg: LookupRegs; 

Offset: UNIV Longlnt; 

VAR S: UNIV DisAsmStr80) ; 

orinC, 

pascal void PCRelProc(long Address, char *S) 

pascal void JTOffProc(short A5JT0ffset, char *S) 

pascal void TrapNameProc(unsigned short TrapWord, char *S) 

pascal void AbsAddrProc(long AbsAddr, char *S) 

pascal void IdProc(LookupRegs BaseReg, long Offset, char *S) 

♦ Note: initLookup contains initialized data that requires initializing at load time. 
This of concern only to users with assembly main programs. 


The Lookup procedure 

PROCEDURE Lookup(PC: UNIV Ptr;BaseReg: LookupRegs;Opnd: 

UNIV LongInt;VAR S: DisAsmStr80); 

This is a standard Lookup procedure available for calls to the Disassembler. If you use 
this procedure, then you must call initLookup prior to any calls to the Disassembler. 
This procedure performs all the logic to determine the type of lookup. For PC-relative, 
jump table references, A-traps, absolute addresses, and offsets from a base register, the 
associated level 1 Pascal procedure specified in the initLookup call (if not NULL) is 
called. 

This scheme simplifies the Lookup mechanism by allowing you to focus on the problems 
related to the application. 

The LookupTrapName procedure 

PROCEDURE LookupTrapName (TrapWord: UNIV Integer; VAR S: UNIV 
DisAsmStr80) ; 

This procedure allows conversion of a trap instruction (in TrapWord) to its 
corresponding trap name (in S). It is provided primarily for use with the Disassembler and 
its address may be passed to initLookup above for use by this unit’s Lookup routine. 
Alternatively, there is nothing prohibiting you from using it direcdy for other purposes or 
by some other lookup procedure. 
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♦ Note: The tables in this procedure make the size of this procedure about 9500 bytes. 
The trap names are fully spelled out in upper and lower case. 


The ModifyOperand procedure 

PROCEDURE ModifyOperand(VAR Operand: UNIV DisAsmStr80); 

The procedure scans an operand string, that is, the null-terminated Pascal string returned 
by the Disassembler (null must be present here), and modifies negative hex values to 
negated positive value. For example, $FFFF(A5) would be modified to -$0001(A5). The 
operand to be processed is passed as the function’s parameter, which is then pHitpd “in 
place” and returned to the caller. 

This routine is essentially a pattern matcher and attempts to modify only 2-, 4-, and St- 
digit hex strings in the operand that “might” be offsets from a base register. If the 
matching tests are passed, the same number of original digits are output (because that 
indicates a value’s size: byte, word, or long). 

For a hex string to be modified, the following tests must be passed: 

■ There must have been exactly 2,4, or 8 digits. Only hex strings $XX, $XXXX, and 
$XXXXXXXX are possible candidates because that is the only way the Disassembler 
generates offsets. 

■ The hex string must be delimited by a left parenthesis character," (” or a comma, “, ”. 
The left parenthesis character allows offsets for sxxxx (An,... ) and $xx (An, xn) 
addressing modes. The comma allows for the MC68020 addressing forms. 

■ The “$x... ” must not be preceded by a plus-or-minus sign, “ ± ”. This eliminates the 
possibility of modifying the offset of a PC-relative addressing mode always generated 
in the form “*±$xxxx”. 

■ The “$x...” must not be preceded by a pound sign, “ # ”. This eliminates modifying 
immediate data. 

■ Value must be negative. Negative values are the only values modified. A value $ffff 
is modified to-$oooi. 

The valldMacsBugSymbol function 

FUNCTION validMacsBugSymbol(symStart: UNIV Ptr;limit: UNIV Ptr; 
symbol:StringPtr): StringPtr; C; 

Check that the bytes pointed to by symStart represent a valid MacsBug symbol. The 
symbol must be fully contained in the bytes starting at symStart, up to but not including 
the byte pointed to by the limit parameter. 
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If a valid symbol is not found, then NULL is returned as the function’s result. However, if a 
valid symbol is found, it is copied to symbol (if it is not NULL) as a null-terminated Pascal 
string, and return a pointer to where we think the following module begins. In the “old 
style” cases (see the following table) this will always be 8 or 16 bytes after the input 
symstart. For new style Apple Pascal and C cases this will depend on the symbol length, 
existence of a pad byte, and size of the constant (literal) area. In all cases, trailing blanks 
are removed from the symbol. 

A valid MacsBug symbol consists of the charactersspaces, digits, and upper and 
lower case letters in a format determined by the first two bytes of the symbol as follows: 


1st byte 
range 

2nd byte 
range 

Byte 

length 

Comments 

$20-$7F 

$20-$7F 

8 

Old style MacsBug symbol format 

$20-$7F 

$20-$7F 

8 

Old style MacsBug symbol format 

$A0-$FF 

$20-$7F 

8 

Old style MacsBug symbol format 

$20-$7F 

$80-$FF 

16 

Old style MacApp symbol ab==>b.a 

$A0-$FF 

$80-$FF 

16 

Old style MacApp symbol ab==>b.a 

$80 

$01-$FF 

n 

n = 2nd byte (Apple Compiler symbol) 

$81 - $9F 

$00-$FF 

m 

m = 1st byte & $7F (Apple Compiler symbol) 


The formats are determined by whether bit 7 is set in the first and second bytes. This bit 
will removed when it is found OR’ed into the first and/or second valid symbol characters. 


The first two formats in the above table are the basic “old-style” (pre-existing) MacsBug 
formats. The first byte may or may not have bit 7 set if the second byte is a valid symbol 
character. The first byte (with bit 7 removed) and the next 7 bytes are assumed to 
comprise the symbol. 

The second pair of formats are also old-style formats, used for MacApp symbols. Bit 7 set 
in the second character indicates these formats. The symbol is assumed to be 16 bytes 
with the second 8 bytes preceding the first 8 bytes in the generated symbol. For example, 
12345678abcdefgh represents the symbol abcdefgh.12345678. 

The last pair of formats are reserved by Apple and generated by the MPW Pascal and MPW 
C compilers. In these cases the value of the first byte is always between $80 and $9F, or 
with bit 7 removed, between $00 and $1F. For $00, the second byte is the length of the 
symbol with that many bytes following the second byte (thus a maximum length of 255). 
Values $01 to $1F represent the length itself. A pad byte may follow these variable length 
cases if the symbol does not end on a word boundary. Following the symbol and the 
possible pad byte is a word containing the size of the constants (literals) generated by the 
compiler. 
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♦ Note: If symstart actually does point to a valid MacsBug symbol, then you can use 
showMacsBugSymbol to convert the MacsBug symbol bytes to a string that could 
be used as a DC.B operand for disassembly purposes. This string explicitly shows the 
MacsBug symbol encodings. 


The endOfModule function 

FUNCTION endOfModule(address: UNIV Ptr;limit: UNIV Ptr;symbol: 

StringPtr; VAR nextModule: UNIV Ptr): StringPtr; C; 

This function checks to see if the specified memory address contains a rts, jmp <ao) 
or rtd #n instruction immediately followed by a valid MacsBug symbol. These 
sequences are the only ones that can determine an end of module when MacsBug symbols 
are present During the check, the instruction and its following MacsBug symbol must be 
fully contained in the bytes starting at the specified address parameter, up to, but not 
including, the byte pointed to by the limit parameter. 

tf the end of module is not found, then NULL is returned as the function’s result However, 
if a end of module is found, the MacsBug symbol is returned in symbol (if it is not NULL) ' 
as a null-terminated Pascal string (with trailing blanks removed), and the function returns 
the pointer to the start of the MacsBug symbol (that is, address+2 for rts or jmp (ao ) 
and address+4 for rtd #n). This address may then be used as an input parameter to 
ShowMacsBugSymbol to convert the MacsBug symbol to a Disassembler operand string. 

Also returned in nextModule is where the following module is expected to begin. In the 
old-style cases (see vaiidMacsBugSymbol) this will always be 8 or 16 bytes after the 
input address. For the new style, the Apple Pascal and C cases, this will depend on the 
symbol length, existence of a pad byte, and size of the constant (literal) area. See 
vaiidMacsBugSymbol for a description of valid MacsBug symbol formats. 

The showMacsBugSymbol function 

FUNCTION showMacsBugSymbol(symStart: UNIV Ptr;limit: UNIV Ptr;operand: 
StringPtr; VAR bytesUsed: INTEGER): StringPtr; C; 

This function formats a MacsBug symbol as a operand of a DC.B directive. The first one 
or two bytes of the symbol are generated as $80+'c' if their high bits are set. All other 
characters are shown as characters in a string constant The pad byte, if present, is also 
shown as $00. 

This routine is called to check that the bytes pointed to by symstart represent a valid 
MacsBug symbol. The symbol must be fully contained in the bytes starting at symstart, 
up to but not including the byte pointed to by the limit parameter. 
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When called, showMacsBugSymbol assumes that symstart is pointing at a valid 
MacsBug symbol as validated by the vaiidMacsBugSymboi or endof Module routine. 
As with vaiidMacsBugSymboi, the symbol must be fully contained in the bytes starting 
at symstart up to, but not including, the byte pointed to by the end parameter. 

The string is returned in the 'operand' parameter as a null-terminated Pascal string. The 
function also returns a pointer to this string as its return value (NULL is returned only if the 
byte pointed to by the limit parameter is reached prior to processing the entire symbol— 
which should not happen if properly validated). The number of bytes used for the symbol 
is returned in bytesused. Due to the way MacsBug symbols are encoded, bytesused 
may not necessarily be the same as the length of the operand string. 

A valid MacsBug symbol consists of the characters '%', spaces, digits, and upper/lower 
case letters in a format determined by the first two bytes of the symbol as described in 
the vaiidMacsBugSymboi routine. 
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Appendix G The Graf3D library 


Graf3D is a set of QuickDraw calls used to produce three-dimensional 
graphics by providing a fixed-point interface to QuickDraw’s integer 
coordinates. This appendix describes these routines and their use for both MPW 
Pascal and MPW C. ■ 
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The Translate procedure 562 
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The Yaw procedure 562 
The Roll procedure 563 
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Overview 


The Graf3D routines provide several important features: 

■ A camera’s-eye view. This allows you to set the point of view from which the observer 
sees the object independently from the coordinates of the object itself. The camera is 
set up with the viewport, LookAt , and viewAngie procedures. You can set the 
focal length of the camera as if you had a choice of telephoto, wide-angle, or normal 
lenses. 

■ Three-dimensional clipping to a true pyramid. The apex of the pyramid is at the point 
of the camera eye, and the base of the pyramid is equivalent to the viewport. When 
you use the ciip3D function, only objects in front of the camera eye and within the 
pyramid are displayed on the screen. 

■ Two-dimensional point and line capability using Fixed type coordinates. GraBD 
provides commands corresponding to the QuickDraw commands but using Fixed 
type coordinates instead of integers. With Fixed type coordinates you have a larger 
dynamic range for graphics calculations; with integer coordinates you get faster 
drawing time. 

■ Two-dimensional or three-dimensional rotation. You can rotate an object along any or 
all axes simultaneously, by using the pitch, Yaw, and Roll procedures. 

■ Translation and scaling of objects in one or more axes simultaneously. Translation 
means movement anywhere in three-dimensional space. Scaling means shrinking or 
expanding. 


How to use GraBD 

This section describes the language-specific preparations you need to make to use 
Graf3D with your MPW Assembler, MPW Pascal, or MPW C programs. 
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How to use Graf3D—MPW Assembler 

To use Graf3D with MPW Assembler, do the following: 

■ Include the file Graf3DEqu.a in your source text. 

■ Link your assembly with the file {Librariesllnterface.o. 

■ Set values in the Graf3D data structures and call the Graf3D routines from your 
program, using the equates in Graf3DEqu.a. 

Throughout the rest of this appendix, Graf3D is described solely in MPW Pascal and MPW 
C notation. The Graf3d routines are implemented in MPW Pascal; Assembly-language 
programmers should call these routines by using Pascal calling conventions. For 
information on how to convert this notation into assembly-language calling conventions 
for stack-based routines, see the chapter “Using Assembly Language” in Inside Macintosh. 


How to use Graf3D—MPW Pascal 

To use Graf3D in MPW Pascal, do the following: 

■ Include the declaration uses Graf 3 d in your source text. 

■ Link your assembly program or object file with the file Interface.o. 

■ Set values in the Graf3D data structures, and call the Graf3D routines from your 
program, following the information given in the section “Graf3D Data Types” that 
follows in this appendix. 


How to use GraBD—MPW C 

To use Graf3D in MPW C, do the following: 

1. Include these statements in your source text: 

#include <Types.h> 

#include <QuickDraw.h> 
finclude <Graf3D.h> 

2. link your object file with the file {libraries} Interface.o. 

3. Set values in the Graf3D data structures and call the Graf3D routines from your 
program, following the information given in the section “Graf3D Data Types” that 
follows in this appendix. 
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Graf3D data types 


Graf3D declares and uses these data types: 

■ Fixed 

■ Point3D 

■ Point2D 

■ XfMatrix 

■ Port3DPtr 

The type Fixed is discussed in Inside Macintosh, Volume 1. The other types are discussed 
in this section. Examples of the calls are supplied in MPW Pascal and MPW C. 


Point3D 

Point 3 d contains three fixed-point number coordinates: x, y, and z. Graf3D uses x, y, 
and z for fixed-point number coordinates to distinguish between the h and v integer 
screen coordinates used by QuickDraw. 

MPW Pascal 

TYPE Point3D = RECORD 

x: Fixed; 
y: Fixed; 
z: Fixed 
END; 


MPW C 

typedef struct Point3D { 
Fixed x, y, z; 

} Point3D; 
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Point2D 


Point2D is just like a Point3D but contains only x- and y- coordinates. 

MFW Pascal 

TYPE Point2D = RECORD 

x: Fixed; 
y: Fixed 
END; 


MPWC 

typedef struct Point2D { 
Fixed x, y; 

} Point2D; 


XfMatrix 

Hie XfMatrix is a 4x4 matrix of Fixed values used to hold a transformation equation. 
Each transforming routine alters this matrix so that it contains the concatenated effects 
of all transformations applied. 

MFW Pascal 

XfMatrix = ARRAY[0..3, 0..3] OF Fixed; 


MPWC 

typedef Fixed XfMatrix[4][4]; 
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Port3DPtr 


The type Port3DPtr contains all the state variables needed to map fixed-point number 
coordinates into integer screen coordinates. 

MFW Pascal 

Port3DPtr = *Port3D; 

Port3D = RECORD 

GrPort: GrafPtr; 
viewRect: Rect; 

xLeft, yTop, xRight, yBottom: Fixed; 
pen, penPrime, eye: Point3D; 
hSize f vSize: Fixed; 
hCenter, vCenter: Fixed; 
xCotan , yCotan: Fixed; 
ident: boolean; 

xForm: XfMatrix 

END; 


MPWC 

typedef struct Port3D { 


GrafPtr 

grPort; 

Rect 

viewRect; 

Fixed 

xLeft, yTop f xRight 

Point3D 

pen r penPrime, eye; 

Fixed 

hSize f vSize; 

Fixed 

hCenter, vCenter; 

Fixed 

xCotan f yCotan; 

char 

filler; 

char 

ident; 

XfMatrix 

xForm; 


} Port3D f *Port3DPtr; 
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■ Table G-l Port3DPtr variables 


Name 

Description 

GPort 

Pointer to the grafPort associated with this Port3D 

viewRect 

Viewing rectangle within the grafPort; the base of the 
viewing pyramid 

xLeft, yTop, 
xRight, yBottom 

World coordinates corresponding to the viewRect 

pen 

Three-dimensional pen location 

penPrime 

Pen location transformed by the xForm matrix 

eye 

Three-dimensional viewpoint location established by 

ViewAngle 

hSize, vSize 

Half-width and half-height of the viewRect in screen 
coordinates 

hCenter, vCenter 

Center of the viewRect in screen coordinates 

xCotan, yCotan 

Viewing cotangents set up by ViewAngle, used by ciip3D 

I dent 

Boolean that allows the transformation to be skipped when 
xForm is an identity matrix 

xForm 

4x4 matrix that holds the net result of all transformations 


Graph3D procedures and functions 


Graf3D provides the following procedures and functions to establish a graphics 
environment and create drawings within it: 

■ The InitGraf procedure 

■ The Open3DPort procedure 

■ The SetPort3D procedure 

■ The GetPort3D procedure 

■ The Move procedures 

■ The Line procedures 

■ The Clip3D function 

■ The SetPoint procedures 

Each procedure and function is described in this section in both MPW Pascal and MPW C. 
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The InitGraftD procedure 


The initGraf 3 d procedure starts up Graf3D and initializes its data structures. GlobalPtr 
is a pointer to heap space for Graf3D data. Call initGraf 3 d once and only once at the 
beginning of your program. Pass it at the address of a Port3DPtr (using the @ operator) 
that you have declared and reserved for use by Graf3D. 


MPW Pascal 

PROCEDURE InitGraf3D(GlobalPtr: Ptr) ; 

MPW C 

pascal void InitGrf3D(port) 

Port3DPtr *port; 

The initGraf 3D function initializes the Port3D variable. Call this routine before doing 
Graf3D operations. Allocate space for a variable of type Port3DPtr (whose address is 
passed as a parameter to this function). 


The Open3DPort procedure 

The 0pen3DPort procedure initializes all the fields of a Port3D to their defaults, and 
makes that Port3D the current one. Gport is set to the currently open graf Port. These 
are the default values: 

thePort3D := port; 
port /v .GPort := thePort; 

Viewport (thePort^ .portRect) ; 

WITH thePort^.portRect DO LookAt(left, top, right, bottom); 
ViewAngle(0); 

Identity; 

MoveTo3D(0, 0, 0); 

MPW Pascal 

PROCEDURE Open3DPort(port: Port3DPtr); 
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MFWC 


pascal void Open3DPort(port) 
Port3DPtr port; 


The SetPort3D procedure 

The SetPort3D procedure makes port the current Port3D and calls setPort for that 
Port3D’s associated grafPort. setPort3D allows an application to use more than one 
Port 3 d and switch between them. 

MPW Pascal 

PROCEDURE SetPort3D(port: Port3Dptr); 

MFWC 

pascal void SetPort3D(port) 

Port3DPtr port; 


The GetPort3D procedure 

The GetPort3D procedure returns a pointer to the current Port3D. This procedure is 
useful when you are using more than one Port 3D and want to save and restore the current 
one. 

MPW Pascal 

PROCEDURE GetPort3D(VAR port: Port3DPtr); 

MFWC 

pascal void GetPort3D(port) 

Port3D *port; 
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The Move procedures 


Graf3D provides four Move procedures that move the pen in two or three dimensions 
without drawing lines. The fixed-point number coordinates are transformed by the xForm 
matrix and projected onto flat screen coordinates; then Graf3D calls QuickDraw’s 
MoveTo procedure with the result. 


MPW Pascal 

PROCEDURE MoveTo2D(x, y: Fixed); 
PROCEDURE MoveTo3D(x, y, z: Fixed); 
PROCEDURE Move2D(dx, dy: Fixed); 
PROCEDURE Move3D(dx, dy, dz: Fixed); 


MPW C 


pascal void 
Fixed 
pascal void 
Fixed 
pascal void 
Fixed 
pascal void 
Fixed 


MoveTo2D(x, y) 
x, y; 

MoveTo3D(x, y, z) 
x, y, z; 

Move2D(x, y) 
x, y; 

Move3D(x, y, z) 
x, y, z; 


The Line procedures 

Graf3D provides four Line procedures that draw two- and three-dimensional lines from the 
current pen location. The LineTo2D and LineTo3D procedures stay on the same z-plane. 
The fixed-point number coordinates are first transformed by the xForm matrix, then 
clipped to the viewing pyramid, then-projected onto the flat screen coordinates and 
drawn by calling QuickDraw’s LineTo procedure. 


MPW Pascal 


PROCEDURE LineTo2D(x, y: 
PROCEDURE LineTo3D(x, y, 
PROCEDURE Line2D(dx, dy: 
PROCEDURE Line3D(dx, dy. 


Fixed) ; 
z: Fixed); 
Fixed); 
dz: Fixed); 
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MPWC 


pascal void LineTo2D(x, y) 
Fixed x, y; 

pascal void LineTo3D(x, y, z) 
Fixed x, y, z; 
pascal void Line2D(x, y) 

Fixed x, y; 

pascal void Line3D(x, y, z) 
Fixed x, y, z; 


The Clip3D function 

The ciip3D function clips a three-dimensional line segment to the viewing pyramid and 
returns the clipped line projected onto screen coordinates. ciip3D returns true 
(nonzero) if any part of the line is visible. If no part of the line is within the viewing 
pyramid, ciip3D returns false (zero). 

MPW Pascal 

FUNCTION Clip3D(srcl, src2: Point3D; VAR dstl, dst2: Point): 
boolean; 


MPWC 

pascal short Clip3D(srcl, src2, dstl, dst2) 
Point3D *srcl, *src2; 

Point *dstl, *dst2; 


The Set Point procedures 

Graf3D provides two Set Point procedures. The setPt3D procedure assigns three fixed- 
point numbers to a Point3D. The SetPt2D procedure assigns two fixed-point numbers 
to a Point2D. 

MPW Pascal 

PROCEDURE SetPt3D(VAR pt3D; Point3D; x, y, z: Fixed); 

PROCEDURE SetPt2D(VAR pt2D; Point2D; x, y: Fixed); 
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MPWC 


pascal void SetPt3D(pt3D, x, y, z) 
Point3D *pt3D; 

Fixed x, y, z; 

pascal void SetPt2D(pt2D, x, y) 
Point2D *pt2D; 

Fixed x, y; 


Setting up the camera 


Procedures viewport, LookAt, and viewAngie position the image in the grafPort, 
aim the camera, and choose the lens focal length in order to map three-dimensional 
coordinates onto the flat screen space. These procedures may be called in any order. 


The Viewport procedure 

The viewport procedure specifies where to put the image in the grafPort. The 
viewport rectangle is in integer QuickDraw coordinates and tells where to map the 
LookAt coordinates. 

MPW Pascal 

PROCEDURE Viewport(r: Rect); 


MPWC 

pascal void Viewport(r) 
Rect *r; 
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The LookAt procedure 

The LookAt procedure specifies the fixed-point number x - and y-coordinates 
corresponding to the viewRect. 

MPW Pascal 

PROCEDURE LookAt(left, top, right, bottom: Fixed); 

MPW C 

pascal void LookAt(left, top, right, bottom) 

Fixed left, top, right, bottom; 


The VlewAngle procedure 

The viewAngie procedure controls the amount of perspective by specifying the 
horizontal angle (in degrees) subtended by the viewing pyramid. Typical viewing angles 
are 0 (no perspective), 10° (telephoto lens), 25° (normal perspective of the human eye) 
and 80° (wide-angle lens). ’ 

MPW Pascal 

PROCEDURE ViewAngie(angle: Fixed); 

MPW C 

pascal void ViewAngie(angle) 

Fixed angle; 
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The transformation matrix 

Use the transformation (xForm) matrix to impose a coordinate transformation between 
the coordinates you plot and the viewing coordinates. Each of the transformation 
procedures concatenates a cumulative transformation onto the xForm matrix. 

Subsequent lines drawn are first transformed by the xForm matrix, then projected onto 
the screen as specified by viewport, LookAt, and viewAngie. 


The Identity procedure 

The identity procedure resets the transformation matrix to an identity matrix. 

MPW Pascal 

PROCEDURE Identity; 


MPW C 

pascal void Identity(); 


The Scale procedure 

The scale procedure modifies the transformation matrix to shrink or expand by xFactor, 
yFactor, and zFactor. For example, 

Scale(X2Fix(2.0), X2Fix<2.0), X2Fix(2.0)) 

doubles the size of whatever you draw. 

MPW Pascal 

PROCEDURE Scale (xFactor, yFactor, zFactor: Fixed); 

MPW C 

pascal void Scale(xFactor, yFactor, zFactor) 

Fixed xFactor, yFactor, zFactor; 
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The Translate procedure 

The Translate procedure modifies the transformation matrix so as to displace by dx, 
dy, and dz. 

MPW Pascal 

PROCEDURE Translate(dx, dy, dz: Fixed); 


MPW C 

pascal void Translate(dx, dy, dz) 
Fixed dx, dy, dz; 


The Pitch procedure 

The pitch procedure modifies the transformation matrix so as to rotate xAngle degrees 
around the x-axis. A positive angle rotates clockwise when looking at the origin from 
positive x. 

MPW Pascal 

PROCEDURE Pitch (xAngle: Fixed); 

MPW C 

pascal void Pitch (xAngle) 

Fixed xAngle; 


The Yaw procedure 

The Yaw procedure modifies the transformation matrix to rotate yAngle degrees around 
the ^-axis. A positive angle rotates clockwise when looking at the origin from positive y. 

MPW Pascal 

PROCEDURE Yaw(yAngle: Fixed); 
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MFWC 


pascal void Yaw(yAngle) 
Fixed yAngle; 


The Roll procedure 

The Roll procedure modifies the transformation matrix so as to rotate zAngle degrees 
around the z-axis. A positive angle rotates clockwise when looking at the origin from 
positive z. 

MPW Pascal 

PROCEDURE Roll(zAngle: Fixed); 


MPW C 

pascal void Roll(zAngle) 
Fixed zAngle; 


The Skew procedure 

The skew procedure modifies the transformation matrix so as to skew zAngle degrees 
around the z-axis. skew changes only the z-coordinate; the result is much like the slant 
that QuickDraw gives to italic characters, (skew (15.0) makes a reasonable italic.) A 
positive angle rotates clockwise when looking at the origin from positive z. 


MPW Pascal 

PROCEDURE Skew(zAngle: Fixed); 


MPW C 

pascal void Skew(zAngle) 
Fixed zAngle; 
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The Transform procedure 

The Transform procedure applies the xForm matrix to src and returns the result as dst. If 
the transformation matrix is identity, dst will be the same as src. 

MPW Pascal 

PROCEDURE Transform (src: Point3D; VAR dst: Point3D); 


MPW C 

pascal void Transform(src, dst) 
Point3D *src, *dst; 
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Appendix H Object File Format 


This appendix is addressed to programmers who are writing compilers or 
assemblers to run under MPW 3.0. ■ 
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About object file records 


Object file format describes the structure of MPW object files. These files are created by 
various language processors (such as MPW Assembler, MPW Pascal, and MPW C) and the 
MPW librarian (Lib). 

An object file consists of a sequence of object file records. The records described in the 
remainder of this appendix are located in the data fork of the object file. MPW object 
files have file type • ob j • and creator • mps *. 

♦ Note: The MPW linker validates only the file type, since other applications than MPW 
may create MPW-compatible object files. 


At the present time the linker tools do not use the resource fork. Although the current 
versions of Link, Lib, and DumpObj will ignore resource fork information in object files, 
Apple may specify resources for object files at some time in the future. 

There are currently 20 types of object file records, numbered consecutively from 0 to 19. 
(Future record types are not guaranteed to have consecutive record numbers). 

Code records: 

■ The first record in the file must be a First record. 

■ The last record in the file must be a Last record. 

■ One-byte Pad records are used to maintain word alignment 

■ Comment records allow comments to be included in the file. 

■ Dictionary records associate names with unique IDs. 

■ Module records define code and data modules. 

■ EntryPoint records define entry points in code and data modules. 

■ Size records specify the module sizes. 

■ Contents records specify the contents of modules. 

■ Reference and ComputedReference records specify locations in modules that 
contain references to other modules or entry points. 
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Symbolic records: 

■ Filename records specify source filenames and modification dates. 

■ SourceStatement records specify correspondence between module offsets and 
source statements. 

■ ModuleBegin and ModuleEnd records declare named scopes (typically associated 
with units, files, or functions). 

■ BlockBegin, and BlockEnd records declare unnamed or “block” scopes contained 
within modules. 

■ LocallD records declare identifiers scoped within modules or blocks. 

■ LocalLabel records specify correspondence between generated code, source 
statements, and label identifiers. 

■ LocalType records define type information for local identifiers and functions. 

A module is a contiguous region of memory that contains code or static data. A module 

is the smallest unit of memory that is included or removed by the linker. An entry point is 

a location (offset) within a module. (The module itself is treated as an entry point with 

offset zero.) A segment is a named collection of modules. 

♦ Note: The jump table (described in Inside Macintosh, Volume II) is considered to be 
code. 


All modules, entries, segments, and symbolic records have a unique 16-bit ID that is 
assigned by the compiler, assembler, or librarian. An ID is an object file-related number 
that identifies a module, entry point, segment, or other entity within a single object file. 


♦ Note: Older versions of the MPW linker support only ID values in the range 1... 16,383. 
The current version accepts ID values in the range 1...65,534 (values 0 and 65,535 are 
reserved). If your compiler needs to be compatible with MPW 2.0, then you should 
restrict the range of IDs accordingly. 


♦ Note: The linker is faster and more efficient if the compiler allocates IDs 
sequentially from 1. 
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Modules and entry points may be local or external. 

■ A local module, entry point, or segment can be referenced only from within the file 
where it is defined 

■ An external module, entry point, or segment can be referenced from different files. In 
addition to an ID, each external module or entry point defined or referenced in an 
object file must also have a unique name (a string identifier) that identifies it across 
files. 

If an ID has a name, that name is specified in a dictionary record. 

If no dictionary entry exists for it, an ID is considered anonymous. 

Local modules and entries need not have unique names, and an external segment may have 

the same name as an external module or entry point. 

♦ Note: Although the names need not be unique, the IDs of these different objects must 
be unique. There must be multiple dictionary entries even though the names are the 
same. If symbolic debugging records are generated, then ModuleBegin records that 
correspond to Module records must also share the same ID. 


A segment is declared implicitly by specifying a segment ID in a code-type Module record. 

At any given point in an object file there can be one current code module and one current 
data module. The beginning of a new code or data module is indicated by a Module 
record. The current code and data modules are further defined by Entry Point, Size, 
Contents, Reference, and Computed-Reference records—these records can occur in any 
order after the Module record. 

In each of these intra-module records, a flag bit indicates whether the record refers to 
the code or the data stream, permitting the interleaving of code and data records by 
compilers. Code and data may be arbitrarily interleaved. For instance, the record 
sequence: 

Module(Code, ID=1) 

Contents, Size, EntryPoint, and reference records for module 1 
Module(Data, ID=2) 

Contents, Size, EntryPoint, and reference records for modules 1 and 2 
Module(Code, ID=3) 

Contents, Size, EntryPoint, and reference records for modules 2 and 3 
Module(Code, ID=4) 

Contents, Size, EntryPoint, and reference records for modules 2 and 4 

declares three code modules and one data module; data module 2’s scope extends until 
the next data module, across an arbitrary number of code modules. 
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Scoping of symbolic information 

All symbolic records contain a parent ID field that specifies the scope to which the record 
applies. These records may be emitted in any order, in any part of the object file. 

Whether the code-generating and the symbolic records are interleaved, nested, or 
completely separated is left to the discretion of the language implementor. (However, 
source statement records for a particular module must be written in order by increasing 
source offset.) 

Executable objects (functions and procedures) are scoped lexically, while variables are 
scoped according to their visibility. To see why this is so, consider the following example 
in C (Pascal UNTTs are similar): 

/* example.c */ 
static int static_var; 
int public^var; 
static local_func() { ... } 
public_func () { ... } 

If 1 pubiic_f unc 1 were contained by the root scope, then it would be impossible to 
access any file-level static variables (such as « static_var *) from within a breakpoint in 
the function. Even though the Module record for 'pubiic_f unc' has its external bit set, 
the ModuleBegin for the function must specify the source file as the parent scope. 

On the other hand, the variable ' pubiic_var ' must be visible to procedures outside 
the file scope, so it is necessary to specify the root as its parent. 
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The records generated for the above example might be: 

First(version=3) 

Dictionary(1, "example.c") 

Fi l ename ( l , modificationDate) 

Dictionary(2, "example.c") 

ModuleBegin(moduleID=2, parentID=0, fileID=l, kind=Unit) 
Dictionary (3, "static_var") 

LocallD (parentID=2, fileID=l, ID=3, type, etc.) 

Dictionary(4, "public_var") 

LocallD (parentID=0, fileID=l, ID=4 f type, etc.) 

Dictionary(5, "local_func”) 

ModuleBegin(moduleID=5 f parentID=2, fileID=l, kind=Function) 
ModuleEnd(moduleID=5) 

Dictionary(6, "public_func") 

ModuleBegin(moduleID=6, parentID=2, fileID=l, kind=Function) 
ModuleEnd (moduleID=6) 

ModuleEnd (moduleID=2, fileOffset) 

Module(ID=5) 

Contents, references, and entry points for module 5 
Likewise, source statement information 

Module(ID=6, flags=external) 

Contents, references, and entry points for module 6 

Likewise, source statement information 

Last 

The symbolic records may appear in any order (ModuieEnds preceding ModuieBegins, 
if necessary), interspersed with the nonsymbolic records (which do have order 
dependencies). There are a few items of interest in this example: 

■ A parent ID of zero indicates the root. 

■ The ID referred to by a Filename record cannot also be referred to by a ModuleBegin 
record. Languages (such as C) which have file scoping will need to produce two 
Dictionary records that have the same name but different IDs: one for the filename, 
the other for the file-level scope. 

■ A point of fine style: The linker is more efficient when multiple entries are emitted in 
the same Dictionary record. Many of the symbolic records also allow multiple 
definitions in the same record, and compiler writers should make use of this facility. 

■ Even though it may be necessary to emit data Module records for variables, it is 
incorrect to emit ModuleBegin records for the data modules; use LocallD records 
instead. 
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ModuleBegin implementation/declaration semantics 


The terms iffipUtmentation and dccluvution refer to ModuleBegin records with the 
isDeclaration bit set at, respectively, zero or one. 

tf a module has only an implementation, the linker assumes the declaration and 
implementation source locations are the same. The first declaration encountered is used, 
except that a declaration in the same object file as the first implementation will override 
any previous declaration. Any declarations or implementations following the first 
implementation are ignored (anything contained in such an ignored scope is also 
ignored). It is legal to have a declaration without an implementation or a Module. 

Module scope information is supplied solely by implementation records; declaration 
records may be nested, but the nesting is ignored since the declaration information does 
not affect mapping between the source and the executable code. 

Local variables (such as parameter variables) and types should be attached to either the 
implementation or declaration, but not to both. 


Record type notation 


This section contains important information about the documentation conventions used 
in the record descriptions that follow. Each record type is represented by a diagram such 
as the following: 
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The fust box illustrates the record. Each square block represents a byte. The first byte 
indicates the record type, in this case, 10. The Flags byte is expanded in the second box. 
The Record Size is a signed, 16-bit integer that indicates the total length of the record 
(including the record type byte, flags byte, and record size field). Hence, any one object 
file record is limited to 32767 bytes. (This is not a limit on the size of the module, because 
partial contents can be placed in several records.) 

The second box represents the flag bits. In this example, they are interpreted as follows: 


Bit 

o"~ 

1,2 

3 

4-5 

6 

7 


Meaning 

0 indicates code, and 1 indicates data 
Must be 0 

0 indicates short, and 1 indicates long 
0 indicates 32 bits, 1 indicates 16 bits, and 2 indicates 8 bits 
Must be 0 

1 indicates a difference computation 


♦ Note: All unspecified bits must be zero. 

In the remainder of this document, names in bit-fields will be specified in numeric order. 
For instance, in the case of the text • local/extern •, the tags local and extern are 
understood to be respectively zero and one. 

The records have been defined so that: 

■ All 16-bit and 32-bit fields are word-aligned in the file. 

■ Fixed-size records do not have a Record Size field. 

■ All variable-length records have a Record Size field. 


Object file records 


This section describes and diagrams each object file record. 
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Pad record 

A pad record is a single byte that is always zero, 
o 


In order to maintain word alignment, a Pad record follows any record whose length is an 
odd number of bytes. (Other than pad records, all records are word-aligned.) 


First record 


The first record in an object file must be a First record. 



If the nested bit in the flags field is one, then the linker interprets all references to 
undefined ID-name pairs as external references. If the nested bit is zero, the li nk er will try 
to match the name of an undefined symbol with a local name before treating the 
undefined symbol as external. 

The version field contains a version number: 

Version number Meaning 

1 Nonsymbolic MPW 2.0 OMF file 

2 Nonsymbolic MPW 3.0 OMF file 

3 OMF file containing symbolic information 
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Last record 


The last record in an object file must be a Last record. 



Comment record 

A comment record allows comments to be included in an object file. 


3 

0 

T 

record size 

SS 

comments 



_1_ 

_ 12 — 


The record size field specifies the total number of bytes in the record. 


Dictionary record 

A dictionary record associates a name with an ID (or several names with several IDs). 


4 

flags 

1 

record size 
„_ 1 

1 

first ID 

1 

strings 

_ 12 _ 






i i n 





LinklD/| 

Dbg ID 1 








7 6 

5 4 

3 

2 

1 

0 


At most one dictionary record may appear for a given ID in a single object file. 

The record size field specifies the total number of bytes in the record. 

The strings field contains one or more names, each of which is preceded by an unsigned 
length byte. 

The first name in the strings field is associated with the ID given in the FirstID field. The 
second name is associated with FirstID + 1, and so on. 
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The dictionary record for an ID must appear before the module or entry-point record that 
defines the ID, but need not appear before reference or computed-reference records that 
refer to the ID. If an ID has no dictionary record or has a name with a length of zero, it’s 
considered anonymous. 

The LinkID/DbgID flag bit is used to differentiate symbolic debugging identifiers from 
code-generating identifiers. When the linker is not linking symbolically it ignores 
dictionary records with this bit set, reducing the Link’s memory requirements. 



Module record 


A Module record associates an ID with a module, and establishes that module as the 
“current” code or data module. All Entry-Point, Size, Contents, Reference, and Computed- 
Reference records combine to define a code or data module. 



Modules may contain either code or data: 

■ For code modules, the segment ID field specifies the segment in which the code is 
placed. Segments may be named or anonymous. Named segments are treated as 
external; anonymous segments are local. (If the segment is named, the dictionary 
record specifying the name must appear before the segment ID can be used in a 
Module record.) 

■ For data modules, a nonzero size field specifies the size of the module. In this case 
Size or Contents records are unnecessary. (The size of a module can also be specified 
by a Size record, or implicitly specified by the offset of the last byte in a Contents 
record.) 

Modules may be either local or external. (Local modules may be anonymous.) 
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A code module flagged as main becomes the execution starting point of the program. A 
data module flagged as main becomes the main program data area, just below the 
location pointed to by A5. At most one main code module or entry point and one main 
data module may appear in an object file. 

If a code or data module has the force-active bit set, then the linker will not strip that 
module even though it is not referenced by any other module and is not the main module. 

References to a module are considered to be references to the first byte of the module. 


♦ Note: The linker ensures that modules are aligned on word or longword boundaries. 


Entry-Point record 

An Entry-Point record declares an entry-point ID. The entry point is in the current code or 
data module, as indicated by bit 0 of the flags field. 



7 6 5 4 3 2 1 0 


The offset field gives the byte offset of the entry point relative to the beginning of the 
module. The offset of an entry point may be outside the module (for example, a virtual 
base for an array). 

An entry point may be defined for either a code or a data module. Entry points may be 
either local or external. (Local entry points may be anonymous.) A code entry point 
flagged as main becomes the execution starting point of the program. At most one main 
code module or entry point may appear in an object file. 
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Size record 

A Size record specifies the size of the current code or data module in bytes. 


7 

flags 


1 1 1 

module size 




1 1 1 



7 6 5 4 3 2 1 0 


The size of a module may also be specified in a Contents record, or (for data modules) in 
the Module record. If more than one size is specified, the largest size given is taken as the 
size of the module. 


Contents record 



7 6 5 4 3 2 1 0 


The record size field specifies the total number of bytes in the record. 

Either complete or partial contents may be specified. If partial contents are specified, 
the first four bytes of the contents field specify the offset of the contents from the 
beginning of the module. 
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The contents may be either the bytes to be placed in the module, or a 2-byte repeat count 
followed by the bytes to be repeated. (If both an offset and a repeat count are 
specified, the offset comes first.) 

Multiple Contents records per module are permitted, in any order. The offset of the last 
byte for which contents are specified determines the module’s total size. (Size 
specifications may also appear in the Module record, and in Size records—if more than 
one size is specified, the largest size given is taken as the size of the module.) 


Reference record 


A Reference record specifies a list of references to an ID. The references are from the 
current code or data module, and may be to either code or data. 


9 

i 

flags record size 

1 

ID 

1 

— 55 

offsets 

_ iZ _ 











relative| 0 j 

0 1 32/16 

short/ 

long 

0 

0 

code/ 

data 


7 6 

5 4 

3 

2 

1 

0 


The record size field specifies the total number of bytes in the record. 

The ID field specifies the module or entry point being referenced. 

The offsets field specifies a list of byte offsets from the beginning of the current code or 
data module. These offsets may be either short (16 bits) or long (32 bits). The location 
modified may be either 32 or 16 bits. Multiple references to the same or overlapping 
locations are permitted. References from code may indicate instruction editing (that is, 
whether an offset is A5- or PC-relative). 

References fall into the four categories described here: 

■ Code-to-code references: If the A5-relative flag is 1, the A5-relative offset of a jump- 
table entry associated with the specified module or entry is added to the specified 
location. No instruction editing is performed. 
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If the A5-relative flag is 0, the linker selects either PC-relative or A5-relative 
addressing. The immediately preceding 16-bit word must contain a JSR, JMP, LEA, or 
PEA instruction, and is modified to indicate either PC-relative or A5-relative 
addressing. If the referenced module or entry point and the current code module are in 
the same segment, the PC-relative offset of the module or entry point is added to the 
contents of the specified location. If they are in different segments, the A5-relative 
offset of a jump-table entry associated with the specified module or entry is added to 
the specified location. 

■ Code-to-data references: The A5-relative flag must be 1 for code-to-data references. 
The A5-relative offset of the specified data module or entry is added to the contents 
of the specified location. No instruction editing is performed. The location may be 
either 16 or 32 bits. (32-bit A5-relative addressing is available for the MC68020, but not 
for the MC68000.) 

■ Data-to-code references: If the A5-relative flag is 1, the A5-relative offset of a jump- 
table entry is added to the specified location, which may be either 16 or 32 bits. 

If the A5-relative flag is 0, the memory address of a jump-table entry associated with 
the specified module or entry is added to the contents of the specified location, 
which must be 32 bits. (Note that this requires a run-time operation that adds the 
actual value of A5 to the A5-relative offset.) 

■ Data-to-data references: If the A5-relative flag is 1, the A5-relative offset of the 
module or entry is added to the specified location, which may be either 32 or 16 bits. 

If the A5-relative flag is 0, the memory address of the specified module or entry is 
added to the contents of the specified location, which must be 32 bits. (Note that 
this requires a run-time operation that adds the actual value of A5 to the A5-relative 
offset.) 

A5 = 0 A5 = 1 


Code-to-Code 

Code-to-Data 

Data-to-Code 

Data-to-Data 


Edit instructbnf 

Force PC-rel if in same segment, 
otherwise add JT-offset. 16 

Mol allou/orl 

Add JT-offset. 

Force PC-relative for non-’CODE’ 
linksf. 32/16 

Add A5-offset of data. 

‘ KJVv6(J 

Add JT offset of code, 
requires load-time addition of A5. 

32 

32/16 

Add JT-offset of code. 

32/16 

Add A5-offset of data. 

Add A5-offset of data. 

requires bad-time addition of A5. 


32 

32/16 


f Edited or forced instructions must be JMP, JSR, I FA or PEA. 
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32-bit code-to-code A5=l references are possible in applications but not non-* code • 
links, because the instruction has to be forced PC-relative for a nonapplication link and 
32 -bit references cannot be edited. 

This MPW Assembly language example exercises all possible modes of fixups except 32-bit 
code-to-code A5=6 which cannot easily be shown in MPW Assembler. Note that further 
instruction editing is done by the linker (for instance, the PC-relative jsr to proc2 
below will be forced A5-relative when the linker realizes that proc2 is in a different 
segment). 
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SEG •SEG1' 

PROC MAIN 

IMPORT PROC1:CODE, PROC2:CODE, DATA1:DATA 

IMPORT _DATAINIT ; 

JSR _DATAINIT ; DO DATA INITIALIZATION 


CODEREFS FORCEJT 
JSR PROC1 
JSR PROC2 
LEA DATA1, AO 


FORCE A5-RELATIVE: 

CODE-TO-CODE, A5=l, SAME SEGMENT 
CODE-TO-CODE, A5=l, DIFFERENT SEGMENT 
CODE-TO-DATA, A5=l 


CODEREFS NOFORCEJT; 
JSR PROC2 

/ 

JSR PROC1 
ENDMAIN 


FORCE PC-RELATIVE: 

CODE-TO-CODE, A5=0, DIFFERENT SEGMENT 
(FORCED A5-RELATIVE BY LINKER) 
CODE-TO-CODE, A5=0, SAME SEGMENT 


DATA1 RECORD 

IMPORT PROC1:CODE, DATA2:DATA 



DATAREFS RELATIVE 

t 

FORCE A5-RELATIVE 





DC. L 

PROCl 

7 

DATA-TO-CODE, A5=l, 

32-BIT 

THROUGH 

A5 


DC. W 

PROCl 

7 

DATA-TO-CODE, A5=l, 

16-BIT 

THROUGH 

A5 


DC. L 

DATA1 

7 

DATA-TO-DATA, A5=l, 

32-BIT 

THROUGH 

A5 


DC. W 

DATA1 

7 

DATA-TO-DATA, A5=l, 

16-BIT 

THROUGH 

A5 


DATAREFS ABSOLUTE 

7 

FORCE ABSOLUTE 





DC.L 

PROCl 

7 

DATA-TO-CODE, A5=0, 

32-BIT 




DC. L 

DATA1 

7 

DATA-TO-DATA, A5=0, 

32-BIT 




ENDR 


7 





PROCl 

PROC 

EXPORT 







ENDPROC 







SEG 

•SEG2' 






PROC2 

PROC 

EXPORT 







ENDPROC 







END 








The “load-lime” addition of A5 is performed by the procedure '_datainit •, which 
appears in the library '{LibrarieslRuntime.o'. 
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The Code-to-Code and Code-to-Data reference modes have obvious utility. The reason 
that non-A5-relative Code-to-Data references are disallowed is that there is no mechanism 
for fixing up code on the Macintosh, which would otherwise have to be done every time a 
segment containing such a reference were loaded. 

C’s pointer initialization makes use of the 32-bit Data-to-Code and Data-to-Data 
reference modes, as in the following examples: 

extern int func(); 

int (*fp) o = func; /* Data-to-Code, 32-bit, load-time addition of A5 */ 
int (**pfp) = &fp; /* Data-to-Data, 32-bit, load-time addition of A5 */ 

The A5-relative Data-to-Code and Data-to-Data reference modes can be used for saving 
space if the application has a large number of pointers to data or code (a dispatch table, 
for instance). 


Computed-Reference record 


A Computed-Reference record specifies a list of computed references based on two 
specified IDs. 


10 

flags 

T 

record size 

1 

“T 

ID1 

1 

r 

ID2 

I 

—>7— 

offsets 

// 


IgsgSgCv: 

Rills 



differ- 1 Q 
ence 

1 

32/16/8 

L 

short/ I 
long 0 

0 

code/ 

data 


7 6 5 4 3 2 1 0 


The record size field specifies the total number of bytes in the record. The references are 
from the current code or data module, and may be to either code or data. 

The ID1 and ID2 fields specify the modules or entry points being referenced. If ID1 
specifies a code reference, ID2 must also be a code reference in the same segment—if ID1 
is a data reference, ID2 must also be a data reference. 

The only computation provided is difference (that is, bit 7 must be set). 

The offsets field specifies a list of byte offsets from the beginning of the current code or 
data module. These offsets may be either short (16 bits) or long (32 bits). The location 
modified may be either 32,16, or 8 bits (a 0 in bits 4 and 5 indicates 32,1 indicates 16, 
and 2 indicates 8). No instruction editing is performed. 
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The value of the address of ID1 minus the address of ID2 is added to the contents of the 
specified location. Multiple references to the same or overlapping locations are 
permitted. 


Filename record 


The Filename record associates a file object with a modification date. 


11 

0 

T 

file ID 

-1-1-1- 

modification date 



_1_ 

_1_1_i_ 


The file ID associates a dictionary ID with a filename. 

The modification date is the file’s modification date. This is used by the debugger to 
help verify that the source file being displayed corresponds to the object file. 

Although the fileED may be used by other records (such as source statements) prior to the 
appearance of the filename record, a Filename record must exist in the file for every filelD 
encountered. In addition, a dictionary ID must exist for the filelD; that is, files cannot be 
anonymous. 


Source Statement record 

The Source Statement record specifies the correspondence between generated code and 
source statements. The debugger uses this information to display source as a function of 
code location. The meaning of “statement’’ is defined by the language and the compiler’s 
author. 
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The record size field specifies the total number of bytes in the record. 

The file ID associates a dictionary ID with a filename. 

The parent ID specifies the scoping entity containing the statement. 

The file offset and code offset specify the source file offset and code or data module 
offset for the first statement specified by this source statement record. These fields may 
be either 16 or 32 signed values. The file offset is the O-relative byte offset in the file 
specified by the file ID. The code offset is the byte offset from the beginning of the 
code or data module for the first byte of code or data corresponding to the statement 
whose offset is specified by the file offset. 

Each additional statement following the one specified by the file and code offset fields is 
specified by a file delta and code delta field. The deltas represent the difference between 
adjacent file and code offsets starting with the one specified by the file and code fields. 
These deltas are in the range from 0 to 255. 

If the subsequent statement cannot be expressed with these offsets, then a new Source 
Statement record should be emitted with new beginning offsets. 

All of the Source Statement records for a module must be emitted in order of increasing 
source code offset. 
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ModuleBegin record 

The ModuleBegin record supplies symbolic information for a module. 



The ^Declaration bit in the flags field provides a way to specify source location 
information for a module’s declaration, if the module’s declaration and implementation 
are separated in the source code (such as a Pascal forward or interface declaration). 

The record size field specifies the total number of bytes in the record. 

The module ID associates a dictionary ID with the record. This ID must be the same value 
used in the Module record. It is through this ID that the connection is made between the 
debugger object file stream for a module and the standard object module stream. 

♦ Note: There doesn’t have to be a Module record associated with the ModuleBegin. If 
there isn’t a module with the same ID then the scope declared by the ModuleBegin is 
treated as a wrapper that doesn’t have any code, but that can contain other symbolic 
objects. This is usually the case when the module-kind field is unit. 


The parent ID specifies the scoping entity that contains the module. An ID of zero 
indicates global scope. This field is ignored if the isDedaration bit is set (parentage 
information is not extracted from a declaration). 

The file ID associates a dictionary ID with a filename. 

The file offset specifies the source file offset for the module header. This field may be 
either 16 or 32 bits and is the O-relative byte offset in the file specified by the file ID. 

The module kind indicates the kind of the module as follows: 
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Kind Description 

0 none 

1 reserved 

2 unit 

3 procedure 

4 function 

5 data module 

6...15 reserved 

A Pascal program’s program level should be treated as a unit (module kind 2). 
The byte following the module kind field is reserved. 


ModuleEnd record 

The ModuleEnd record is associated with a ModuleBegin record by the moduielD field. 


14 

flags 

i 

module ID 

1 1 

1 I r 

file offset 

_1_1_1_ 












1 ' S 

I decl'n 




7 6 5 4 3 2 1 0 

The file offset specifies the last byte in the source file that is to be considered part of the 
module. The isDeclaration bit specifies whether the file offset reflects the end of the 
module’s implementation or declaration. 
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BlockBegin record 


A BlockBegin record declares a nested scope. Usually these scopes don’t have names, but 
it’s OK to associate a dictionary ID with the block scope for symbolic naming purposes 
only; the ID can’t also be associated with another object (such as an entry point). 


15 

flags 

- 1 - 

record size 

J _ 

- 1 - 

Block ID 

_1_ 

1 

Parent ID 

_L 









mmmmm 

liilili' 


file 

offset 
32/16 | 

1 code 

offset 
| 32/16 







7 

6 

5 

4 

3 

2 

1 

0 


The record size field specifies the total number of bytes in the record. 

The parent ID specifies the scoping entity (such as the block or module) containing the 
block. It’s illegal to specify a parent of zero, or to specify a parentage chain that doesn’t 
(eventually) include a {ModuleBegin, Module} pair; there must be a linkable object in the 
chain. 

The file ID and file offset specify the source file and source file offset of the first 
statement within the block. 

The code offset specifies the offset of the first instruction in the block. The offset is 
relative to the module that the block appears in, and does not depend on any intervening 
scopes between the BlockBegin and the module in which it appears. 

A Block scope can’t contain another ModuleBegin scope. 
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BlockEnd record 

The BlockEnd record indicates the end of a block. There must be a block end record for 
each BlockBegin record. 




! 

i i r 

”i i r 

16 

0 

BlockID 

file offset 

code offset 



_1_ 

_1 1 1 

_ 1 _ 1_1_ 


The file offset specifies the last byte in the source file that is to be considered part of the 
block. 

The code offset specifies the offset within the containing module of the first instruction 
not to be treated as part of the block. 


Local Identifier record 

Local Identifier records specify formal parameters to procedures and functions as well as 
local identifiers (and their types) declared within modules or blocks. 
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The record size field is used to determine the number of IDs which follow. 

The parent ID specifies the scoping entity (such as module or block) containing the 
identifier. 

The file ID associates a dictionary ID with a filename. 

The file offset specifies the source file offset for the first statement specified by this 
Local Identifier Record. This field may be either a 16- or 32-bit signed value giving the 
zero-relative byte offset in the file specified by the file ID. 

Following the initial file offset one or more sets of 5 fields will provide information about 
local identifiers. 

The ID associates a dictionary ID with a formal parameter or a local variable. 

The type is a type ID specifying the identifier's type. For primitive types, this ID will 
range from 0 to 99; for nonprimitive types it will be the ID (>100) of die LocalType record 
describing the type. 

The File Delta byte specifies the identifier’s source offset (The first delta byte will 
usually be zero.) If the delta for the variable is not in the range 0..255 then a new record 
must be started. 
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The Kind byte is used to determine whether the identifier is in fact a formal parameter, a 
function return “parameter,” or a local variable. The Kind field also specifies the size of 
the byte offset which follows, as well as the storage mode for the parameter or variable. 

The offset size field indicates whether there is a byte offset field present, and if there is, 
how large it is. If it is three, a 16-bit count field specifies the number of bytes that follow 
the count (used for representing floating-point or string constants). If the count is odd, a 
pad byte should be added to the data. 

offset size _ description _ 

0 no offset field follows 

1 2-byte offset field 

2 4-byte offset field 

3 variable size offset field (preceded by 16-bit count) 

The reference and value bits in the Kind field must be 0 in the case of local identifiers, and 
must be specified in the case of formal parameters. 


storage class 

description 

offset is the... 

0 

register 

register number 

1 

A5-relative 

ID of the module or entry point 
corresponding to this variable 

2 

A6-relative 

A6-relative offset 

3 

A7-relative 

A7-relative offset 

4 

absolute 

absolute address 

5 

constant 

value of the constant 

6...15 

reserved 

reserved forfuture use 


A7-offsets (storage class 3) are encoded as offsets from the top of the stack (usually the 
return address) prior to executing a link instruction. 

Register numbers are encoded as integers indicating the specific register as follows: 
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■ Table H-l Register numbers 


Value 

Register 

Meaning 

0..7 

D0..D7 

Data registers 

8..15 

A0..A7 

Address registers 

16 

CCR 

Condition code register 

17 

SR 

Status register 

18 

USP 

User stack pointer 

19 

MSP 

Master stack pointer 

20 

SFC 

Source function code register 

21 

DFC 

Destination function code register 

22 

CACR 

Cache control register 

23 

VBR 

Vector base register 

24 

CAAR 

Cache address register 

25 

ISP 

Interrupt stack pointer 

26 

PC 

Program counter 

27 


reserved 

28 

FPCR 

Floating-point control register 

29 

FPSR 

Floating-point status register 

30 

FPIAR 

Floating-point instruction address register 

31 


reserved 

32..39 

FP0..FP7 

Floating-point data registers 

40..50 


reserved 

51 

PSR 

PMMU status register 

52 

PCSR 

PMMU cache status register 

53 

VAL 

PMMU validate access level register 

54 

CRP 

PMMU CPU root pointer register 

55 

SRP 

PMMU supervisor root pointer register 

56 

DRP 

PMMU DMA root pointer register 

57 

TC 

PMMU translation control register 

58 

AC 

PMMU access control register 

59 

see 

PMMU stack change control register 

60 

CAL 

PMMU current access level register 

61..62 

TT0..TT1 

MC68030 transparent translation registers 

63 


reserved 

64..71 

BAD0..BAD7 

PMMU breakpoint acknowledge data registers 

72..79 

BAC0..BAC7 

PMMU breakpoint acknowledge control registers 
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Local Label record 

Local Label records give the correspondence between generated code, source statements, 
and label identifiers. 



These records are similar to Source Statement records. 

The flags, record size, parent ID, file ID, file offset, and code offset fields are identical to 
those fields in the Source Statement record (see description earlier in this appendix). 

The file delta and code delta are also encoded as they are in Source Statement records, 
but here an additional label ID field is supplied with each file and code delta pair. The 
label ID associates a dictionary ID with a label identifier. The first label ID in the Local 
Label record has no file and code delta following it since that ID is at the location 
specified by the file and code offset fields. 
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Local Type record 


Local Type records associate type declarations with type IDs (or several types with 
several IDs). Type IDs are used to define types referred to by LocallD and other Local 
Type records. 



The record size field specifies the total number of bytes in the record. 

The parent ID specifies the scoping entity (such as a module or block) containing the 
identifier. 

The 32/16 size bit in the flags field specifies whether the physicalSize fields of all type 
declarations in the record are 16 or 32 bits. 

The 32/16 file offset bit in the flags field specifies whether the fileOffset field is 16 or 32 
bits. 
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Bit zero of the flags field must be zero. 

The firstID field specifies the first type ID declared by the record, • first id + i ' is 
associated with the second type declared, and so on. The first type ID should be > 100; 
IDs 0 through 99 are treated as “primitive” types and should never be defined by a 
LocalType record. 

The filelD field specifies the dictionary ID containing the source filename. If the file ID 
is 0 then the type declarations in the record are not associated with any source code, and 
the fileOffset and fileDelta fields are ignored (though they must appear). 

The fileOffset field specifies the offset of the type declaration in the source file. This is a 
16-bit or 32-bit unsigned value, as determined by the 32/16 file offset bit in the flags field. 

Type declarations immediately follow the firstID field, and extend to the end of the 
record. For each declaration the following fields appear: 

■ The sizeOfData field specifies the size of the type data in bytes. (If this field is odd, 
a pad byte of zero must follow the type data.) 

■ The cntOfFixups field specifies the number of type ID and dictionary ID fixups that 
follow the type data. 

■ The physicalSize field is either 16 or 32 bits (see definition of the flags field) and 
specifies the type’s physical representation size, in bytes (such as the value returned 
by C’s sizeof operator). This field may be inaccurate for packed types and sliced 
arrays, and is meaningless for ProcOf types. 

■ The type data follows the physicalSize record. The format of the type data is 
described in the following section, “Type Interpretation via Prefix Code.” If the size 
of the type data is odd then a pad byte of zero must be appended to it. The pad byte 
is not included in the size of the type data. 

■ Following the type data is the fixup list, consisting of cntOfFixups entries. Each fixup 
entry is two words: an offset into the original type data followed by an ID to translate. 
The ID is translated and the result is inserted into the type data at the specified 
offset. The upper three bits of the fixup offset indicate the kind of translation to be 
made; the remaining bits are the type data offset. The translation kinds are: 
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bit 

15 

bit 

14 

bit 

13 

Translation treatment 

0 

0 

0 

Insert the Tl't index of the ID (which must be a LocalType or a number from 

0 to 99) as a 16-bit word 

0 

0 

1 

reserved 

0 

1 

0 

Insert a scalar based on the ID’s type: 

Module insert MTE index of the module 

LocallD insert CVTE index of the variable 

Segment insert RTE index of the segment 

Source file insert FRTE index of the source file 

LocalType insert TTE index of the type 

0 

1 

1 

reserved 

1 

0 

0 

Insert NTE index of the ID, as a scalar 

1 

0 

1 

reserved 

1 

1 

0 

reserved 

1 

1 

1 

reserved 


(MTEs, CVTEs, RTEs, FRTEs, and TTEs and so forth are part of the Sym file produced 
by the linker, and are described in the document SADE Sym File Format, which is 
available separately from Developer Technical Support at Apple Computer, Inc.) 

■ The fileDelta field indicates the source file offset of the next type declaration as a 
signed 16-bit integer. This field does not appear following the last type declaration in 
the record. If the source offset will not fit in 16 bits, then a new Local Type record 
should be started. 

A type ID is associated with a name by a “Dbgld”-type dictionary entry with a 
corresponding ID. 

A new Local Type record should be started whenever the source file changes, when the file 
delta cannot be represented in a 16-bit signed integer, or when a type has no source 
declaration. 


Type interpretation via prefix code 

The goals of type interpretation are to support the interpretation of SADE debugger 
variables by type, map from name to type, and map from type information to name. 
Operators such as array indexing, indirection, field name, and so on, are applied to types 
to yield more type and address information. 
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The type information should be complete. By complete is meant that the debugger should 
have a minimum amount of knowledge about how data for any particular type is stored. 
Type information should be easy for compilers to emit and for the linker to extract from 
the Object module format. The storage of type information should be compact, yet fast 
and easy to expand. High-level language interpreters for type information should not be 
prohibitively expensive. 


Overview 

SADE type information is contained in word aligned variable length data structures called 
Type Table Entries, (TIE). These type table entries are contiguously numbered (starting at 
100, as the indices 0.. 99 are reserved) and accessed via an indexing table of four byte 
disk addresses. An index into this table is called a TIE Index. The type table entries are 
aligned on word (two byte) boundaries. No global/local scope information is contained 
in the type table; scoping is via the Modules table and its Contained Modules, Types, and 
so on. A picture of a TIE appears later in this appendix. 

The TypeCodes portion of a TTE contains size information and an interpretative 
representation of a type. The exact form for the TypeCodes is described below. The 
paradigm used for the SADE type mechanism is types as functions. All types are either 
basic types or functions with types and integral constants as arguments. The realization 
of this paradigm is prefix code: an operator followed by operands. 

Type values are either scalar types or composite types. Instances of a scalar type can be 
ordered, while composite types cannot necessarily be ordered. Scalar types are further 
divided into integral and nonintegral scalar types. Integral types can be mapped to the 
set of integers. 


Type functions 

Following are the definitions for the type functions and their arguments. Except for two 
cases, type function arguments are either other type functions, encoded scalars, or 
instances of a scalar type (see the section “ScalarOP). In one exception, ConstantOfC ), 
one argument is a sequence of uninterpreted bytes. In the other, TTE(), the argument is 
an unaligned 2 bytes interpreted as an unsigned word. Except in these two cases, the 
convention used is to prefix arguments with S if it is a scalar or T if it is a type or an 
instance of a type. 
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BasicType(SType) 

This function returns a ground type, one which cannot be composed of other typest. The 
argument is an integer in the range 0-99. By convention, the empty type, called void, is 
represented by BasicType(0). 


TTE(UnsignedWord) 

The type, and also the name for the type, is found at the UnsignedWord entry in the type 
table. This aliasing function allows the association of a name to a type, or the factoring- 
out of a shared anonymous type into one common entry, thus saving table space. 

PointerTo(Ttype) 

The argument is a type. The value of the function is pointer to that type. 

PointerTo(void) is a generic pointer, equivalent to the C type (void *). 

ScalarQf(Ttype, Svalue) 

The type returned by the ScalarOf function names an instance of given scalar type. The 
ScalarOf function is usually referred to by RecordOf or EnumerationOf. 

NamedTypeOf(Snte, Ttype) 

The scalar is an index for a Name Table Entry. That entry gives the name for the type 
Ttype. This mechanism is used to give names which are local to a type, such as record and 
union field names. 


ConstantOf(Ttype, Slength, byte...) 

The function ConstantOf is similar to ScalarOf, except that the constant can be of a 
nonintegral type, such as floating-point constants or composite type constants. The 
TType is the type of the constant, the Slength is the number of bytes in the constant, and 
the unencoded bytes following are the bytes comprising that type. 


1 This is not quite true. Due to historical reasons, strings are considered a ground type instead of a derived type. 
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EnumeratlonOf(Tbase, Slower, Supper, Snelements, Ttype...) 

The function EnumerationOf names an enumeration type. Tbase names the underlying 
scalar type that the elements of the enumeration are drawn from. It also determines the 
storage size of the Enumeration. Usually, the elements are drawn from 
BasicType(SignedWord). The Slower and Supper are the lower and upper bounds of the 
enumeration. Snelements is the number of Ttype elements named as part of the 
enumeration. Snelements can be less than Supper Slower +1 if the enumeration is sparse, 
as is possible with C enums. 


VectorOf(Tlndex, Telement) 

The function takes two arguments. The first is the index type, which is the scalar type 
from which the vector indices are drawn. The second argument is the type of the vector 
elements. The value of the function is Array [Tindex] OF Telement. 

RecordOf(Snflelds, Soffset & Ttype...) 

The function RecordOf returns a type composed of a linear sequence of types. Snfields is 
the number of types in the composite type. The argument types are pairs of a scalar and a 
type. The Soffset scalar gives the offset to that element from the beginning of the type. 
The Ttype is the type of that element The offsets are byte offsets. The representation 
details are discussed in the following section. 

UnlonOftTtag, Soffset, Snfields, Tvariant & Ttype...) 

The Union function could be built from the RecordOf function. Ttag is the scalar type of 
the tag. For C and other languages whose unions do not have a tag, Ttag is the ground type 
void. Soffset is the offset to the first variant from the start of the union. If there is no 
tag variable, then Soffset will be 0. Otherwise, Soffset is the size of the rag variable plus 
any required alignment. The Snfields is the number of variants in the union. The Tvariant 
and Ttype pairs define one element of the union. The Tvariant is an instance of the Ttag 
and names the variant If Ttag is void, Tvariant is void. Ttype is the field of the union. 


SubRangeOffTbase, Tlower, Tupper) 

The function SubRangeOf names a subrange of the scalar type, Tbase. The bounds of the 
subrange are given by the Tlower and Tupper values. 
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SetOf(Tbase) 


The function SetOf names a set type. The set is composed of elements drawn from scalar 
type Tbase. 

ProcOf(SClass, TRetura, SArgc, TArg...) 

The function ProcOf names a procedure type. SClass is the class of procedure. The class 
of the procedure defines how arguments are passed to it and values are returned from it. 
TRetum is the type of the return value; if void the ProcOf names a procedure instead of a 
function. SArgc is the number of arguments to the procedure. The TArg are the arguments 
to the procedure. The argument order is the order of declaration, as it appears in the 
source text. How the TArgs are actually passed, on the stack, Pascal or C, or in registers, is 
as per the SClass. 

ValueOfCTtype, Scvte, Smte) 

The scalar value, of type Ttype, can be obtained by fetching the variable whose CVTE 
index is Scvte and whose containing module’s MTE index is given by Smte. Smte is 
required because the variable named by the Scvte might be in a register or relative to A6, 
requiring a debugger to find the proper stack frame. Ttype will be the same as the type in 
the CVTE; it is duplicated because it’s not desirable to reference the CVTE just to find the 
type. 


AirayOfifTelement, Sorder, Sndlrm, Tboundl,...) 

The ArrayOf type descriptor is used to describe monolithic arrays, those which cannot or 
should not be described with VectorOf functions. The Telement is the type of each array 
element Sorder describes how the address of an element is computed from the array 
indices. Sndim is the number of dimensions of the array, and Tboundl... are the indexing 
types, usually SubRangeOf types. 

Sorder can have one of two values. If 0, then the address of array(i,j,k) is computed by 

(i-lowerBouruXyboundl)) + 

Q-lou&rBound(Tbomd2)) * #w«(Tboundl) + 

(k-lowerBoundUbomd5)) * #ww(Tbound2) * #>a<Tboundl) 

If 1, then the address is computed by 

(\-fowerBoundybo\m&Vj) * sp<zn(Tbound2) * sp«r<Tbound3) + 

(j-/ou^BoundCfl»und2)) * spa nflboundl) + 

(k-lowerBoundCTbonndi)) 
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where 


lowerBound Type) = lower bound of the subrange or enumeration 

upperBourtdJype ) = upper bound of the subrange or enumeration 

spaiiTypt) = upperBound Type) - lowerBoundJype) 

Note the difference in the order of the element type and index type from that in the 
vectorof function. This was done to keep the variable number of bounds as the last 
arguments to the ArrayOf function. 


Representation of type information in the SADE symbol table 

The SADE symbol table, created by the linker from information in the object mnHnlps 
linked, stores type information in a type table Entry. The type table Entry is a word- 
aligned variable-length data structure of the form: 



NTE index 

The NTE index is a 4-byte field, giving the name of the type via an index into the Name 
Table. The index can be zero, meaning that this is an anonymous type. 


Physical Size 

The Physical Size 2-byte field defines the number of bytes taken up by the TypeCodes 
field. It does not include the physical size or logical size fields. Hie maximum size of a 
TypeCodes field is 1023 bytes. The other bits are flag bits. Of these flag bits, only one, 
the B bit, is defined. The other bits are reserved for future expediencies and should be set 
to zero. The B bit applies to the Logical Size and means Big. When set, the logical size 
field will be 4 bytes instead of 2, allowing the description of very large data structures such 
as Fortran arrays. 
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Logical Size 

The Logical Size field is either 2 bytes or 4 bytes wide. If the B bit in the Physical Size 
field is zero, then the Llogical Size is 2 bytes long. If set, the field is 4 bytes long. In either 
case, the value of the field is the number of bytes required to store the type. 

TypeCodes 

Following the header information are the TypeCodes themselves. This is a sequence of 
Physical Size bytes of type information. The TypeCodes are described in the next 
section. 


Representation of type codes 

Type function codes are single bytes. The Basic Type function has the Most Significant 
Bit (MSB) of the byte 0 and the basic type number encoded in the lower 7 bits. The Type 
Composition Function has a 1 in the MSB and the function code in the lower 6 bits. The 
next-to-MSB is a flag indicating the type of offset encountered in the arguments to that 
type. If zero, then offsets are byte offsets from the beginning of the type. If 1, then 
offsets are bit offsets from the beginning of the type. 


Basic type 



The byte names a Basic type in the range 0.. 99. The standard values for Basic types are 
named earlier in this appendix and are as follows: 
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0 no type 

1 Pascal string 

2 unsigned long word 

3 signed long word 

4 extended (10 bytes) 

5 Pascal boolean (1 byte) 

6 unsigned byte 

7 signed byte 

8 character (1 byte) 

9 character (2 bytes) 

10 unsigned word 

11 signed word 

12 singled 

13 double 

14 extended (12 bytes) 

15 computational (8 bytes) 

16 C string 

17 as-is string 


Type composition function 


1 P 


O .. 63 


The type code is in the lower 6 bits. The P bit means the type is packed. The default, 
P=0, means that the type is unpacked. The values for the type codes are: 

1 TTE 

2 PointerTo 

3 ScalarOf 

4 ConstantOf 

5 EnumerationOf 

6 VectorOf 

7 RecordOf 

8 UnionOf 

9 SubRangeOf 

10 SetOf 

11 NamedTypeOf 

12 ProcOf 

13 ValueOf 

14 ArrayOf 

The SClass for ProcOf types has the following immediate meanings: 
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0 Undefined 

The calling conventions of the function are undefined. 

1 Pascal 

The calling convention follows Pascal conventions. The return value or a pointer to the return 
value is placed on the stack and is then followed by a fixed number of arguments. The called 
procedure/function cleans up the stack before returning to the caller. 

2 C with fixed arguments 

C calling convention. The caller removes any arguments that were passed. The arg count is the 
number that was specified in the prototype for the C function or in the function definition. 

3 C with variable number of arguments 

Similar to the above, except that the argument count is the minimum number of arguments to 
pass to the function. It is suggested that compilers emit a ProcOfO, TRetum, 0) for functions 
referenced without prototypes or function definitions, as that is the most general case. This is 
especially useful for declarations of pointers to function. 


Representation of scalars 


o 


0 .. 127 


A constant in the range 0-127 fits into a single byte. The high bit is zero, marking this as a 
small integer. 


1 1 -63 .. -1 


If the 2 high bits of a byte are one, then the byte represents a small negative integer in the 
range -63 -1. The value -64, with the lower 6 bits zero, is used as switch to long. 

See below. 


1 o 


O .. 16383 


If the two high bits of a byte are 10, then a larger integer in the range 0.. 16383 is specified 
by appending the next byte to the 10 byte and stripping off the high two bits of the word. 
The constant is not aligned to word boundaries. 
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1 

1 

0 

0 

0 

0 

0 

0 


4 bytes of longint 


A byte whose value is -64 is used for expansion past the preceding bounds. The four bytes 
following (not aligned to word boundaries) are the longint. 


Examples 

In these examples, it is assumed that “Integer” is the name of a BasicType of SignedWord. 


Pascal source 


TYPE 


VHSelect 


= (v, h); 


Point = 

RECORD 

CASE Integer OF 


0 : 


1: 


(v: Integer; 
h: Integer); 

(vh: ARRAY [VHSelect] OF Integer); 


END; 


Rect 

RECORD 

CASE Quux: Integer OF 
0:(top: Integer; 


left: 
bottom: 
right: 

1: (topLeft: 

botRight: 


Integer- 
Integer; 
Integer); 
Point; 
Point); 


END; 


Possible object module representation 

The representation of type information in the object module must be less compact than 
in the type table so that the linker will not have to interpret the type information, just 
resolve linkages, fold anonymous types into types referring to them, and emit the 
compacted information. The differences are: 

■ TTE(x) are replaced by the dictionary numbers of the entries. 

■ BasicType(x) are replaced by dictionary numbers less than 100. 
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In the following, dictionary numbers are distinguished from integers. BasicType(n) 
should be viewed as having been replaced by the canonical dictionary for that type. 


Met * 

3000 

3010 

3020 

3050 

3052 

3054 


3056 

3060 


3132 


3134 


3140 


Name 

v 

h 

VHSelect 

vh 


Point 


Rect 


Type definition _ 

ScalarOf(3020, 0) 

ScalarOf(3020, 1) 

EnumerationOf(BasicType (0), 0, 1, 2, 3000, 3010) 
VectorOf(3020, BasicType(INTEGER)) 

ScalarOf(BasicType(INTEGER), 0) 

RecordOf( 

/* Record has two fields */ 

2, 

/* First, at offset 0, is the "v: Integer”*/ 
/* Two bytes after it is ”h: Integer”*/ 

0, NamedTypeOf(”v”, BasicType(INTEGER)), 

2, NamedTypeOf(”h”, BasicType(INTEGER)) 

) 9 

ScalarOf(BasicType(INTEGER), 1) 

UnionOf( 

/* Two variants. Integer selector, no tag */ 

2, BasicType(INTEGER) , 

3052, 3054, /* 0: selects the record of 

"v" and ”h” */ 

3056, 3050 /* 1: selects the array of 

two ints */ 

) 

RecordOf( 

4 9 

0, NamedTypeOf("top", BasicType(INTEGER)), 

2, NamedTypeOf("left", BasicType (INTEGER)), 

4, NamedTypeOf("bottom”, BasicType(INTEGER)) , 
6, NamedTypeOf("right", BasicType(INTEGER)) 

) 

RecordOf( 

2/ 

0, NamedTypeOf("topLeft”, 3060), 

4, NamedTypeOf("botRight", 3060) 

) 

UnionOf( 

/* Two variants. Integer selector, 
tag is "Quux", size 2 */ 

2, NamedTypeOf("Quux", BasicType(INTEGER)), 2 
3052, 3132, /* 0: First variant is the 

record of 4 Integers */ 

3056, 3134 /* 1: Second variant is the 

record of 2 Points */ 


) 
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Possible compilation into TTE 

The linker can compact the representation, folding anonymous entries into the type 
definitions referring to them. This would yield the following: 


3100 

V 

ScalarOf(TTE(3102), 0) 

3101 

h 

ScalarOf(TTE(3102). 1) 

3102 

VHSelect 

EnumerationOf (BasicType (SignedWord) „ 0, 



TTE(3101)) 

3105 

vh 

VectorOf (TTE (3102), BasicType (Integer) ) 

3106 

Point 

UnionOf( 


TTE (3100), 


/* Two variants. Integer selector, no tag */ 
2, BasicType ( Integer) , 


/* 0: selects the record of "v" and "h" */ 
ScalarOf (BasicType (Integer) , 0), 

RecordOf( 

/* Record has two fields */ 

2 , 


/* First, at offset 0, is the 
"v: Integer" */ 

0, NamedTypeOf ("v", BasicType (Integer) ), 

/* Two bytes past the first, is 
"h: Integer" */ 

2, NamedTypeOf("h", BasicType (Integer) ) 

), 

/* 1: selects the array of two ints */ 

ScalarOf (BasicType (Integer) , 1), 

TTE(3105) 

) 
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3114 


Rect 


UnionOf( 


/* Two variants. Integer selector, 
tag is "Quux", size 2*/ 

2, NamedTypeOf ("Quux", BasicType (Integer) ), 2 

/* 0: First variant is the record 
of 4 Integers */ 

ScalarOf (BasicType ( Integer) , 0), 

RecordOf( 

4, 

0, NamedTypeOf("top”, BasicType( INTEGER) ), 

2, NamedTypeOf("left”, BasicType (Integer) ) , 

4, NamedTypeOf("bottom”, BasicType (INTEGER)), 
6, NamedTypeOf("right", BasicType (Integer) ) 

), 


/* Is Second variant is the record 
of 2 Points */ 

ScalarOf(BasicType("Integer"), 1), 
RecordOf( 

2 , 

0, NamedTypeOf("topLeft", 3106), 
4, NamedTypeOf("botRight", 3106) 
) 

) 


Type interpretation and packed data 

The previous section did not describe packed data, such as Pascal’s packed arrays 
(actually vectors) and records and C’s bit-field structures. This proposal for describing 
packed data rests on the observation that it is not the composite types that are packed 
but rather components of the composite types. The solution is general enough to solve 
today’s problem and be extensible to future language implementations. 

When a type has the packed attribute, it is followed by packing information. The 
packing information describes the packing for that occurrence of the type. In the case of 
the VectorOf composing type, the packing information describes how a given number of 
elements are arranged within a fixed number of bytes. 
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Storage framework 

In general, an instance of a datatype is a sequence of bits. These bit sequences are usually 
aligned on address boundaries and are totally contained within an integral unit of 
addressable units of storage (bytes). Packing an instance of a datatype minimizes the 
amount of wasted bits, possibly at the expense of access time. Therefore, the packed 
type information assumes the following bit-level view of K bytes of storage, with the 
most significant bit (and byte) at the left and the least significant bit (byte) at the right: 



A packed data field is represented by two scalars: the MSB and ISB. The scalars are 
represented as described in the TypeCodes document. This allows bitfields and packed 
data to be from 1 to 2**32—1 bits wide*. The number of bytes occupied by that packed 
data field is (MSB+7) DIV 8. LSB can be thought of as the shift factor and MSB-LSB+1 
the number of bits in the mask. 

A packed non- VectorOf type is followed by a single occurrence of MSB and LSB. 

Packed vectors have a regular structure. A group of vector elements, M, will be packed 
into a number of bytes, N. The packing is regular, meaning that the bit field for 
Vectorfp*M+k] is the same as that for Vectorlk] except that it is p*N bytes after Vectorlk]. 
Because of this regularity, the bitfield information is in a different format: 


‘t Originally, it was thought that the packed data field could be represented by a single byte of mask and shift information. 
One nibble in the byte represented the field width (0 to 15 bits) in the word. The position of the field was represented by 
the other nibble as the number of bits to left shift the mask. However, one common case, the C bitfield with more than 15 
bits, prevents a single byte representation for packed data. Since more than one byte is required to represent packed data, 
the MSB/LSB view was adopted. 

MSB/LSB was chosen over MASK and SHIFT because one less addition is required to yield the number of bytes required 
for the data type. 
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7zZ] 





C 

T3 


The first scalar gives N, the number of bytes into which the M vector elements can fit. The 
next scalar gives the width of the bit mask. The third scalar gives M, the number of 
elements in the repeating group. Following these three scalars are M scalars. These M 
scalars give the LSB for the O’th to the M-l’th vector element. LSB[i]+# Bits/Elements-1 
gives MSB[i]. 


Examples 

The following example is in C and from Harbison and Steele. It is assumed to follow 
MC68000 addressing in that the most significant bytes are at the lowest addresses. Also 
note that the example assumes that this particular C compiler packs fields into ints 
starting with the least significant bit of the int. 


Here is a sample bitfield: 


Sx 

Segment | 

Page 

Offset 




| 


31 29 23 15 0 


C source 

typedef struct { 


unsigned offset : 

16; 


unsigned page 


: 8; 

unsigned segment : 

6; 


unsigned : 

1; 

/* For future use */ 

unsigned supervisor 
} V ADDR; 


• J- * 
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Possible compilation into TTE 

The preceding fields are not all packed fields. Only the segment and supervisor fields 
need to have the packed attribute applied to them. Those two fields are followed by the 
bit positions within the byte. 

3107 V_ADDR RecordOf( 

4, 

/* First is "offset". Note its byte offset */ 

2, NamedTypeOf("offset", «UnsignedInteger»), 

/* Next is "page".It is physically before "offset" */ 
If NamedTypeOf("page", «UnsignedInteger»), 

/* Finally, "Segment" and "Supervisor" in byte 0*/ 

0, packed NamedTypeOf ("segment", 

«UnsignedInteger»), 5, 0, 

0, packed NamedTypeOf ("supervisor", 

«UnsignedInteger»), 7, 7 

) 
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Appendix I In Case of Emergency 


This appendix contains some information that may be useful 
when serious system errors occur. ■ 

Contents 

Crashes 615 
Stack space 615 





Crashes 


If you end up in the MacsBug debugger while running MPW, it may be possible to recover 
without rebooting and losing your recent changes. Type g sysrecover. The Shell will 
attempt to recover by aborting the current command, saving the contents of all the 
windows, and/or returning to the Finder. If this fails, type es to return to the Finder, then 
shut down the system immediately. 


Stack space 

The MPW Shell and tools that run integrated with the Shell share a single stack. The stack 
size is determined by the Shell at initialization time. Complex command files, large links, 
and other tools may require more stack space than is available. System errors 28, 2, and 3 
are possible indications of this problem. You can increase the stack size by using ResEdit 
to modify ’ hexa • resource number 128 in the file MPW Shell. The default size is $2710 
(10,000 bytes) when less than 480,000 bytes are available for the application heap and 
$4E20 (20,000 bytes) when more than 480K are available. 
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Glossary 


abstract target: In Make dependency rules, a 
target that is not actually built but represents a 
collection of items. Use an abstract target to 
trigger dependencies on the right side of the 
dependency rule. See Chapter 9 for details on 
Make dependency rules. 

active window: The frontmost window. The 
Shell variable {Active} always contains the name 
of the current frontmost window. 

alias: An alternate name for a command, 
defined with the Alias command. 

application: A program that runs stand-alone, 
outside of the Shell environment. An 
application’s file type is APPL. 

author: In Projector, with respect to a 
particular revision, the name of the person who 
made a revision. With respect to Projector’s 
files and projects, the person with the primary 
responsibility for a file or project. 

blank: A space or a tab character (in the 
context of separating words in the command 
language). 

branch: In Projector, an additional sequence of 
revisions emanating from another revision and 
running parallel to the main trunk. 

build commands: Shell commands that are 
output by the Make tool, used to build a 
program. 

build command line: In the dependency rule 
of a makefile, the lines beginning with a space or 
tab that follow the dependency line. 


built-in commands: Editing commands, 
structured commands, and other Shell 
commands that are part of the MPW Shell 
application (as opposed to MPW tools, which 
are separate files on the disk.) 

Checkout directory: The directory into which, 
by default, Projector places checked out files. 
Each project has a corresponding Checkout 
directory which can be changed with the 
CheckOutDir command. 

'ckid' resource: The “check ID” resource that 
Projector maintains in the resource fork of all 
files belonging to a project The 'ckid' resource 
contains identification such as User name, Task, 
Project, and so on. 

code resource: A resource that contains a 
program’s code—most commonly a resource of 
type ’CODE' (for applications and MPW tools) 
but also other resource types such as ’DRVR’ and 
'PDEF that also contain code. 

command file: See script 

command name: The first word of a 
command, identifying the name of a built-in 
command or the name of a file (tool, command 
file, or application) to execute. 

command script See script 

command substitution: The replacement of a 
command by its output. Command substitution 
takes place within back quotes ('...'). 

comment In Projector, user-supplied text 
describing a particular revision, file, or project. 
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console: The window where a command is 
entered and executed (standard input). Also, 
the window to which the command’s output is 
returned (standard output). 

current project: In Projector, the name of the 
current project. Projector assumes all actions 
pertain to this project unless a different project 
is specified with the ^project option. 

current selection: The currendy selected text 
in a window. In editing commands, the current 
selection in the target window is represented by 
the $ metacharacter. 

data fork: The part of a file that contains data 
accessed via the Macintosh File Manager. 

data initialization interpreter: The module 
_DATAINIT in the libraries Runtime.o and 
CRuntime.o. 

dead code: In the linker, modules that cannot 
be reached from any references available, given 
a main module. See “Dead Code” in Chapter 8 
for more information. 

dependency file: A makefile. 

dependency line: In Make, the first line of a 
dependency rule. See also: dependency rule. 

dependency rule: In Make, a rule that 
specifies the prerequisite files of a given target 
file, along with a list of the commands needed 
to build the target file. 

dependent: In a Commando dialog, a control 
that is enabled or disabled depending on the 
state of its parent control. 

derez: To decompile a resource file by using the 
MPW resouce decompiler, DeRez. 

desk accessory: A “mini-application,” 
implemented as a device driver, that can be run 
at the same time as an application. Desk 
accessories are files of type DFIL and creator 
DMOV, and are installed by using the Font/DA 
Mover. 

device driven A program that controls the 
exchange of information between an 
application and a device. 


diagnostic output: Commands and tools send 
error and progress output to diagnostic output 
(by default, the window where the command 
was executed). You can redirect diagnostic 
output to another file, window, or selection 
with the > and >> operators. Diagnostic output 
is also referred to as “standard error.” 

dialog: In Commando, the programmed 
interaction between a user and a tool or script. A 
dialog may utilize more than one dialog box. 

dialog box: A window that appears when a 
command is invoked, offering options and 
parameters. 

Directed Acyclic Graph: The MPW linker 
creates a tree of all reachable modules from a 
given main module. See “Dead Code” in Chapter 
8 for more information. 

Editor: When appearing with initial capitals, 
the built-in commands appearing in MPWs Edit 
menu, a part of the MPW Shell. 

entry point: A location (offset) within a 

module. 

escape character: The Shell escape character is 
3 (Option-D). It is used to disable (or “escape”) 
the special meaning of the character following 
it, to continue commands over more than one 
line ©Return), and to insert invisible characters 
into command text. 

external: A module, entry point, or segment 

that can be referenced from different object 
files. 

external reference: A reference to a routine or 
variable defined in a separate compilation or 
assembly. 

file information: Information maintained by 
Projector on a per-file basis. Examples are: 
Author, Last Modification Date, and Comment. 

filename: A sequence of up to 31 printing 
characters (excluding colons), that identifies a 
file. See also pathname. 

file type: A four-character sequence, specified 
when a file is created, that identifies the type of 
file. (Examples: TEXT, APPL, MPST.) 
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Finder information: Information that the 
Finder provides to an application upon starting 
it, telling it which documents to open or print. 

Font/DA Mover: An application, available on 
the System Tools disk, used for installing desk 
accessories in the System file. 

full pathname: See pathname. 

HFS: Hierarchical File System used on 800K 
disks and the Apple hard disks. 

ID: A file-relative number for identifying a 
module, an entry point, or a segment, within a 
single object file. 

insertion point: An empty selection range; that 
is, the character position where text will be 
inserted (marked with a blinking vertical bar). 

Integrated Environment: A set of routines, 
modeled on the C language, that provide 
parameter passing, access to variables, and 
other functions to MPW tools. (See Chapter 12 
and Appendix F.) 

interface routine: A routine called from C, 
Pascal, or Assembler whose purpose is to trap to 
a certain ROM or library routine. 

jump table: A table that contains one entry for 
every routine in an application or MPW tool, and 
is the means by which the loading and unloading 
of segments is implemented. 

leafname: A partial pathname that contains no 
colons. A leafname might be a directory and a 
filename, such as “Tools.-ResDet” or simply a 
filename. MPW assumes the default directory. 
See also: pathname and partial pathname. 

literal: In the resource compiler, Rez, a value 
within single quotation marks. (See Chapter 8.) 

local: A module, entry point, or segment that 
can be referenced only from within the file where 
it is defined. 

location map: The linker can write to standard 
output a map of memory segments sorted by 
segNum and segOffset. (See Chapter 10.) 

locked revision: In Projector, a revision 
currently checked out for modification. 


main segment: The segment containing the 
main program or procedure. 

makefile: Used by the Make command, a file 
that describes dependencies between the 
various pieces of a program, and contains a set 
of commands for building up-to-date files. The 
default makefile is named MakeFile. 

module: A contiguous region of memory that 
contains code or static data. A module is the 
smallest unit of memory that is included or 
removed by the linker. 

mounted project: In Projector, a project that 
is not nested within another project. Similar to 
the root directory on a volume. You can mount 
several projects, just as you can mount several 
volumes. You can access all projects under the 
mounted project. 

MPW Shell: The application that provides the 
environment within which the other parts of the 
Macintosh Programmer’s Workshop operate. 
The Shell combines an editor, command 
interpreter, and built-in commands. 

MPW tool: An executable program (type 
MPSD that is integrated with the MPW Shell 
environment (contrasted with an application, 
which runs stand-alone). Like applications, tools 
exist as separate programs on the disk. 

name: In Projector, an identifier that represents 
a set of files, revisions, and branches, with the 
restriction that a name can refer to only one 
revision in any one file. 

non-HFS: The nonhierarchical file system, used 
on 400K disks and Macintosh XL hard disks. 

option: A command-line switch, specifying 
some variation from a command’s default 
behavior. Options always begin with a hyphen (- 

orphaned file: In Projector, a file that belongs 
to a project, but whose resource fork no longer 
contains the information that Projector needs 
to determine to which project it belongs. 
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parameter: The words following the keyword in 
a simple command. There are two types of 
parameters: options and files. Note that certain 
parameters, such as I/O redirection, are 
interpreted by the Shell and never seen by the 
command itself. 

parent: In Commando, an option or control 
whose status determines whether a dependent 
option or control is enabled or disabled. 

partial pathname: A pathname that either 
contains no colons or has a leading colon. See 
also: leafname. 

pathname: A sequence of up to 255 characters 
that identifies a file, directory, and/or volume. 

A full pathname contains embedded colons but 
no leading colon. It specifies volume: 
directory:...filename. A partial pathname either 
contains no colons or has a leading colon. A 
partial pathname is convenient to use if the file 
is located in the current default directory. A 
leafname is a partial pathname that contains no 
colons. See also: leafname, partial pathname. 

pattern: A literal text pattern (such as 
/ABCDEFG/), or a regular expression. Patterns 
are a case of selection and always appear 
between the pattern delimiters /.../ or \ ...\. 

pipe: The command terminator I is the pipe (or 
pipeline) symbol. It causes the output of the 
preceding command to be used as the input for 
the subsequent command. (See Chapter 5, 

Table 5-1.) 

position: In editing commands, position refers 
to the location of the insertion point. 

prefix: The directory portion of a filename. 

prerequisite file: In Make, the files that must 
exist or be up-to-date before the target file can 
be built. 

project: In Projector, a set of files that may 
include other projects (subproject). 

project directory: The directory in which 
Projector maintains all the project-management 
information about a given project. 


project file: In Projector, the file (always named 
ProjectorDB) in which an entire project is 
maintained. There is one and only one project 
file within every project directory. 

project information: Information maintained 
by Projector on a per-project basis, including: 
author, last modification date, and comment. 

project name: In Projector, the name of a 
project as well as the name of the directory 
containing that project. 

ProjectorDB: In Projector, the name of the 
database file in which Projector stores all 
information about projects, their revision trees, 
revisions, and branches. 

project tree: In Projector, the set of mounted 
projects 

pseudo-filename: Any device name that you 
can use in place of a filename but that has no 
disk file associated with it. Any command can 
open a pseudo-filename. These are most often 
used for I/O redirection. 

quotes: A set of characters that literalize the 
enclosed characters, used for disabling special 
characters. The quote symbols are 
\...\, and /.../. The escape character, 9, quotes 
the character that follows it 

reference: The location within one module that 
contains the address of another module or entry. 

regular expressions: A language for specifying 
text patterns, using a special set of 
metacharacters. (See Appendix B, Table B-2.) 

regular expression operators: A special set 
of metacharacters used in regular expressions 
and filename generation. (See “Pattern 
Matching” in Chapter 6.) 

resource Data or code stored in a resource file 
and managed by the Macintosh Resource 
Manager. 

resource attribute: One of several 
characteristics, specified by bits in a resource 
reference, that determine how the resource 
should be dealt with. 
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resource compiler: A program that creates 
resources from a textual description. The MPW 
resource compiler is named Rez. 

resource description file: A text file that can 
be read by the resource compiler and compiled 
into a resource file. The resource decompiler 
disassembles a resource file, producing a 
resource description file as output. 

resource file: Common usage for the resource 
fork of a Macintosh file. 

resource fork: The part of a file that contains 
data used by an application, such as menus, 
fonts, and icons. An executable file’s code is 
also stored in the resource fork. 

revision: In Projector, an instance of a file in a 
project. A new revision is created each time a 
modified file is checked in. 

revision information: Information maintained 
by Projector on a per-revision basis. Also known 
as the current state of a revision. For unlocked 
revisions this includes: Author, Creation date, 
Comment, and Task. For locked revisions the 
information is: Author (person who checked out 
the file), Check-out Date, and Task. 

revision tree: In Projector, the composite 
history of a file; that is, all the revisions and 
branches made to a file. The revision tree for a 
file can be displayed via the Status command or 
by double clicking a filename in the Project 
hierarchy frame of the Check In and Check Out 
windows. 

root: In a makefile, a top-level target that is not 
a prerequisite of any other target. 

scaling: In graphics, to shrink or expand an 
image. See Appendix G: The Graf3D library for 
more information. 

scope: In Projector, the current project 

script: An ordinary text file (type TEXT) 
containing a series of commands. The entire file 
can be executed by entering the filename. A 
script is also referred to as a command file or 
command script. 


segment: One of several parts into which the 
code of an application may be divided. Not all 
segments need to be in memory at the same 
time. 

selection: A series of characters, or a character 
position, at which the next editing operation 
will occur. Selected characters are inversely 
highlighted in the active window, and outlined 
in other windows. A selection is used as an 
argument to most editing commands and can be 
specified by using a special set of selection 
operators. (See Appendix B, Table B-l.) 

signal: An event that diverts program control 
from its normal sequence. (See Chapter 12.) 

signature: Each Macintosh application has its 
own unique signature (or creator). For example, 
creating a file with the type DFIL and signature 
DMOV tells the Font/DA Mover that this file 
contains desk accessories. See the Finder 
Interface chapter-of Inside Macintosh. 

simple command: Any command consisting 
of a single keyword followed by zero or more 
parameters. 

standard error: See “diagnostic output.” 

standard input: Input to a command, usually 
typed directly into the active window (the 
console). 

standard output: Output produced by most 
commands that is returned to an open file, 
usually the window in which its command or 
program was typed. 

Startup file: A special command file containing 
commands that are executed each time the Shell 
is launched. Startup executes a second 
command file called UserStartup. 

status panel: The panel in the lower left comer 
of the Worksheet window. The status panel 
shows what command MPW is executing. 

Clicking in the status panel is equivalent to 
pressing the Enter key. 
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status value: A code returned by commands in 
the Shell variable {Status}. Zero indicates 
successful completion of the previous 
command, and other values usually indicate an 
error. 

structured command: Any command that 
controls the order in which other commands are 
executed. For and If are examples of structured 
commands. All structured commands are built 
into MPW and usually have more than one 
keyword. See also simple command. 

subproject: In Projector, any project 
contained within another project. Subprojects 
may, in turn, contain other subprojects. 

target selection: The current selection in the 
target window, represented by the § character. 

target file: In Make, a file that is to be rebuilt 
and that depends on one or more prerequisite 
files. 

target window: The second window from the 
front—this is the default target for editing 
commands that are entered in the active 
window. The Shell variable {Target} always 
contains the name of the current target window. 

task: In Projector, a short description of the 
task that a user accomplished with a revision. 

{task}: In Projector, the name of the current 
task. It appears in die Check Out and Check In 
windows as the default task. 

tool* See MPW Tool. 

type declaration: In the resource compiler, a 
statement that specifies the pattern for any 
associated resource data by indicating data 
types, alignment, size, and placement of strings. 

translation: In graphics, movement anywhere in 
three-dimensional space. See Appendix G: The 
Graf3D library for more information. 

trunk: In Projector, the main sequence of 
revisions to a file. Branches from any revision 
are always named and numbered with respect to 
the trunk. 

users: In Projector, those persons with access 
to the files of a project. 


{user}: In Projector, the name of the current 
user. Projector logs this name with all 
transactions. You can override this name by 
specifying a different name with the -u option 
available in all Projector commands. 

user Interface: The system or set of 
conventions by which the user interacts with 
software. In addition to the standard Macintosh 
mouse-and-menu interface, MPW includes both 
a command language and a dialog user interface 
(Commando). 

word: A single, blank-separated element in a 
command. A command name and each of its 
parameters are separate words in the command 
language. 

Worksheet window: The main work area in 
MPW; the window usually used as the console. 
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tutorial 50 
modifying 259 
building 

desk accessories 
limitations 258 
location of code 258 
result code 257 
desk accessory 254 

steps in building 251 
driver 254 

steps in building 251 
drivers 

calling sequence 257 
structure of 257 
MPW tools 350 

stand-alone code resources 248 


steps in creating 248 
building a program 
introduction 49 
new program 54 
steps 241 
bulldozer 194 
bundle bit 243 

C 

C compiler 34 
C++ translator 34 
case sensitivity 186 
Caution 

on use of global variables 254 
CC170 

changing directories 101 
characters 145 
asterisk 

in regular expressions 187 
case sensitivity of 186 
character list 186 
colon 183 

current selection 162,167 
escape 148 

exclamation mark 179 

in filename generation 145 
infinity 167 
integral character 227 
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transforming output 192 
Duplicate 144 
Echo 157 

use of 146,321 

entering and executing 89-91,124-125 
Exit 155 


Export 142 

example of use 143 
expressions used in 157-160 
file-management 95-97 
Files 

use of 144 

Files, use with Count 345 
Find dialog box 70 
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Touch Mod date 208, 215 
tutorial 201-207 

checking in a revision 204-209 
checking out a revision 209-217 
creating a new project 201-202 
locating a project 209 
user field 207,213 
user privileges 230 
using Checkout 217 
View By dialog box 221-222 
warning on 'ckid' 208 
warning on orphan files 208 
ProjectorDB file 224, 235 
projects 
definition 197 
protected bit 

in resource description statements 322-323 
pseudo-filenames 165-166 
table of 166 

Q 

Quit 131-132 
quoting 146-149 
in makefiles 275-276 
quoting spaces 149 

R 

RAM cache 46 
with Link 296 
read 370 

read-only files 103-104 
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rectangle types 316 

redirecting input/output 160-162 

redirection 

in Commando 425-426 
reference 
in linking 291 
reformatting tables 188 
regular expression operators 183-185 
asterisk character 187 
character expressions 185 
character list 186 
examples 191-193 
finding a whole word 193 
forward and backward searches 190 
inserting invisibles 189 
matching pattern at beginning or end of line 
189 

negation symbol 186 
plus sign 187 
repeated 187 
table of 184 
tagging 188 

transforming DumpObj output 192 
wildcard operators 186 
® operator 188 
ResEdit 38, 241 
ResEquaLr 442 
resource attributes 311 
resource compiler see Rez 
resource declarations 304 
resource decompiler see DeRez 
resource description files 303 
Commando numbering of 418 
comments 306 
for Commando 397 
preprocessor directives 307 
sample Commando resource 442 
structure of 306 
type declarations 306 
resource description statements 
$$countof 
use of 317 
align types 316 
array types 317-318 
boolean types 315 
built-in functions 325-326 


change 321 
character types 314 
cstring 315 
data 311 
data-type 313 
delete 320 
escape characters 339-340 
fill types 317 
include 308-309 
labels 326-330, 512 

declaring in arrays 326-327 
examples 328-330 
limitations 327 
numeric types 313-314 
bitstring 313 
byte 313 
integer 313 
longint 313 
pstring 316 
read 310 

resource statements 323 

sample resource description file 323 

sample type statement 319 

special terms 308 

string 315 

string types 314-315 

strings 338-340 

syntax 308, 335 

expressions 335-336 
numbers and literals 334-335 
type 311-312 
variables 336-338 
wstring 315 
resource editor 
definition 38 
resource files 

creating and modifying 304-305 
resource fork 244 
resource types 
defining 306 
resources 
CDEF 248 
LDEF248 
MDEF 248 
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owned by desk accessory 255 
WDEF248 
XCMD 248 
restrictions 
MPW tools 346-347 
Resume 131 

revision trees 197, 228-229 
revisions 
definition 197 
number 198 
Rez 35,303-340 
array types 317-318 
change resource data 321 
data statements 323-314 
delete a resource 320-321 
escape characters 339-340 
fill and align types 316 
point and rectangle types 315-316 
preprocessor directives 330-333 
if-then-else processing 332 
print directive 332-333 
variable definitions 331 
sample type statement 319 
specify actual resource data 322-323 
strings 338-340 
switch types 318-319 
symbolic definitions 319-320 
symbolic names 324 
variables 336-338 
Rez and link 
sequence of use 243 
RIncludes 251 
{Rlndudes} directory 
contents 304 
RIncludes folder 
Cmdo.r 392 
ROM interfaces 

guidelines for special libraries 299 
ROM maps 450 

S 

SADE38 

sample programs 49-50 
scoping 570-571 
scripts 31,39,168-170, 260 


AddMenuAsGroup 169 
CC170 

definition 130 
examples 168 
Line 133 
parameters 141 
Quit 131 

referencing command parameters 126 
Repeat 156 
Resume 131 

special MPW scripts 131-132 
Startup 131 
Suspend 131 

use of pseudo-filenames 166 
used by Directory and Build menus 260 
useful commands for use in 157 
UserStartup 131 
UserVariables 139 
using variables 142 
search path 101 
segmentation 288-290 

case sensitivity of names 289 
length limit 289 
selection 175-193 
automatic 182 
by line number 179 
extending 183 

forward and backward searches 190 
markers 180-182 
MPW Shell abilities 361 
operators 

order of precedence 177 
pattern 182 
pattern matching 183 
position 180 
specifications 98 
selection expression 

Find-and-Replace dialog 73 
setting a file type 245 

setting protected bit on code resources 321 
setup of MPW files 40 
setvbuf 365 
Shell 

features 61 
file format 62 
summary of shortcuts 94 
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summary of variables 94 
variables 377 
Shell commands 30 
SIG_IGN384 
signal 384-385 
signal handling 383-387 
caution about heap corruption 387 
MPW C 383,385 
MPW Finder 383 
MPW Pascal 384,385 
types 385 
Signal.p 352 
signature 247 
single / dependency 268 
slashes 147,148 
software interrupt 
as signal handling 383 
specifying files with wildcards 103 
specifying pathnames with variables 102 
stand-alone code resources 248 
Standard I/O buffering 364-366 
standard input 90,160,162 
important note 93 
standard output 90,161,164 
start up 46-48 
Startup 131 
Startup file 48,131 
status code 125,345-346 
status panel 47,91,124 
stderr 365-366 
st din 365-366 
stdio 365-366 
stdout 365-366 
storing Shell commands 
in Assembler 358 
in Pascal 358 
streams 365 
String 338-34Qs 
constants 

desk accessories 258 
operators 159 
Rez 340 

structured commands 29 
Stubs.o 351 
Suspend file 131 


symbolic names 

in resource description statements 325 
in Rez 320 
symbols 145 
asterisk 

in regular expressions 187 
beginning of line metacharacter 189 
colon 183 

considered as separate words 150 
corrupt ’ CKID ' resource icon 207, 236 
current selection 162,167,178 
end of line metacharacter 189 
escape character 

used to insert invisibles 189 
escape conventions 150 
exclamation mark 179 
expression operators 158 
expressions 157-160 
infinity 167 
integral 227 

lock icon 206, 212, 236, 237 
modified read-only icon 206, 236 
negation 186 
newline 178 

pencil icon 206, 212, 236, 237 
plus sign 

in regular expression 187 
project icon 212, 237 
read-only icon 206, 236 
regular document icon 206, 212, 236, 237 
regular expression operators 
table of 184 
revision tree icon 212 
selection operators 176 
special 

useofl60 
® operator 188 
syntax 

in resource description statements 335 
resource description statements 
expressions 335-336 
Rez language 308 
SysTypes.r 304 
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tagging operator 159 
target window 89,167,174 
terminating input 163 
TermPerf 451,462 
text patterns 
comparing 159 
Time Manager 

in performance measurement 451 
TIOFLUSH 374 
tools 

editing, table of 175 
tutorial 49-57 
Types.r 304 

typing commands 90-91 
U 

UserStartup 131 

Directory and Build menu scripts 260 
UserVariables 139 
USES files 

Build commands with 261 
V 

variable 
{Targ} 268 
variables 

$$Attributes 309 
$$ID309 
$$Name 309 
$$Type309 
ArgV 357 

built-in makefile variables 275 
defined in Startup 135-138 

referenced by editor 137-138 
table of 136,137,138 
defining 142 

defining variables within a makefile 274 
defining with Set 133 
exporting 142-143 
extern variables 

in desk accessories 258 
hints for using {DirectoryPath} 102 
how to use in scripts 141 


IEString type 357 
in makefiles 273-276 
in Rez 336-338 

in Rez preprocessor directives 330-333 
names 134 

pathnames for libraries and Include files 138 
QuickDraw globals 

in desk accessories 258 
Rez string variables 310 
Shell variables in makefiles 273-274 
StandAlone 355 
static variables 

in desk accessories 258 
true/false values 134 
UNIT variables 

in desk accessories 258 
use of 133-134 
{Active} 135,174 
{AIncludes} 138 
{Aliases} 135,392 
{AOptions} 271 
{Asm} 271 
{Autoindent} 137 
{Boot} 135 

{CaseSensitive} 137, 186 
{CIncludes} 138 
{Clibraries} 138 
{Commando} 136, 392 
{Commands} 136 
{Command} 135 
{COptions} 271 
{C} 271 
{Default} 271 
{DepDir} 272 
{DirectoryPath} 140 
{Echo} 136 
{Exit} 136 
{Font} 137 
{FontSize} 137 
{IgnoreCmdPeriod} 140 
{Libraries} 138 
{NewWindowRect} 140 
{Parameters} 141 
{Pascal} 271 
{PInterfaces} 138 
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{PLibraries} 138 
{POptions} 271 
{PrintOptions} 137 
{Program} 259 
{RIncludes} 138 
{SearchBackward} 137 
{SearchType} 137 
{SearchWrap} 137 
jshellDirectory} 135 
{StackOptions} 140 
{Status} 135 
{SystemFolder} 135 
{Tab} 137 
{TargDii} 272 
{Target} 135,174 
{Test} 136 
{TileOptions} 140 
{Used 230 

{Windows} 135,392 
{WordSet} 138 
{Worksheet} 135 
{ZoomWindowRect} 140 
VBL 

in performance measurement 451 
Vertical Blanking signal 
in performance measurement 451 


names 97 

New Project 201-204 
Projector 

retrieving information 220-223 
reading projector windows 236 
target 89,167,174 
window commands 26 
worksheet 47 
worksheet window 47 
write 371 

Writing a signal handler 386-387 

Z 

zero-width characters 69 


warning 
buffering 366 

calls to EmptyHandle 348 
CheckOutDir 224 
NIL master pointers 348 
on performance measurement 449 
on use of SIG_DFL 386 
wildcards 103 
notation 146 
operators 

in regular expressions 186 
•WIND’ 

sample window resource file 323-324 
windows 

active 89,167,174 

Check In window 205-206 

MPW Shell input/output abilities 361 
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APPLE COMPUTER, INC SOFTWARE LICENSE 

PLEASE READ THIS LICENSE CAREFULLY BEFORE USING THE 
SOFTWARE. BY USING THE SOFTWARE, YOU ARE AGREEING 
TO BE BOUND BY THE TERMS OF THIS IICENSE. IF YOU DO 
NOT AGREE TO THE TERMS OF THIS LICENSE, PROMPTLY 
RETURN THE UNUSED SOFTWARE TO THE PLACE WHERE YOU 
OBTAINED IT AND YOUR MONEY WILL BE REFUNDED. 

1. License. The application, demonstration, system and other software 
accompanying this License, whether on disk, in read only memory, or on 
any other media (the “Apple Software”) and related documentation are 
licensed to you by Apple. You own the disk on which the Apple Software 
is recorded but Apple and/or Apple's Licensors) retain title to the Apple 
Software and related documentation. This License allows you to use the 
Apple Software on a single Apple computer and make one copy of the 
Apple Software in machine-readable form for backup purposes only. You 
must reproduce on such copy the Apple copyright notice and any other 
proprietary legends that were on the original copy of the Apple Software. 
You may also transfer all your license rights in the Apple Software, the 
backup copy of the Apple Software, the related documentation and a copy 
of this License to another party, provided the other party reads and agrees 
to accept the terms and conditions of this License. 

2. Restrictions. The Apple Software contains copyrighted material, 
trade secrets and other proprietary material and in order to protea them 
you may not decompile, reverse engineer, disassemble or otherwise 
reduce the Apple Software to a human-perceivable form. You may not 
modify, network, rent, lease, loan, distribute or create derivative works 
based upon the Apple Software in whole or in part. You may not 
electronically transmit the Apple Software from one computer to another 
or over a network. 

3. Support You acknowledge and agree that Apple may not offer 
any technical support in the use of the Software. 

4. Termination. This License is effective until terminated. You may 
terminate this License at any time by destroying the Apple Software and 
related documentation and all copies thereof. This License will terminate 
immediately without notice from Apple if you fail to comply with any 
provision of this License. Upon termination you must destroy the Apple 
Software and related documentation and all copies thereof. 

5. Export Law Assurances. You agree and certify that neither the 
Apple Software nor any other technical data received from Apple, nor the 
direa product thereof, will be exported outside the United States except as 
authorized and as permitted by the laws and regulations of the United 
States. 

6. Government End Users. If you are acquiring the Apple Software 
on behalf of any unit or agency of the United States Government, the 
following provisions apply. The Government agrees: 

(i) if the Apple Software is supplied to the Department of Defense 
(DoD), the Apple Software is classified as “Commercial Computer 
Software” and the Government is acquiring only “restricted rights” in the 
Apple Software and its documentation as that term is defined in Clause 
252.227-7013(cXD of the DFARS; and 

(ii) if the Apple Software is supplied to any unit or agency of the 
United States Government other than DoD, the Government’s rights in the 
Apple Software and its documentation will be as defined in Clause 52.227- 
19(c)(2) of the FAR or, in the case of NASA, in Clause 18-52.227-86(d) of 
the NASA Supplement to the FAR. 

7. Limited Warranty on Media. Apple warrants the disks on which the 
Apple Software is recorded to be free from defects in materials and 
workmanship under normal use for a period of ninety (90) days from the 
date of purchase as evidenced by a copy of the receipt. Apple’s entire 
liability and your exclusive remedy will be replacement of the disk not 


meeting Apple’s limited warranty and which is returned to Apple or an 
Apple authorized representative with a copy of the receipt. Apple will 
have no responsibility to replace a disk damaged by accident, abuse or 
misapplication. ANY IMPLIED WARRANTIES ON THE DISKS, INCLUDING 
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
A PARTICULAR PURPOSE, ARE LIMITED IN DURATION TO NINETY (90) 
DAYS FROM THE DATE OF DELIVERY. THIS WARRANTY GIVES YOU 
SPECIFIC LEGAL RIGHTS, AND YOU MAY ALSO HAVE OTHER RIGHTS 
WHICH VARY FROM STATE TO STATE. 

8. Disclaimer of Warranty on Apple Software. You expressly 
acknowledge and agree that use of the Apple Software is at your sole risk. 
The Apple Software and related documentation are provided “AS IS” and 
without warranty of any kind and Apple and Apple's Licensors) (for the 
purposes of provisions 8 and 9, Apple and Apple’s Licensors) shall be 
collectively referred to as "Apple") EXPRESSLY DISCLAIM ALL 
WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
A PARTICULAR PURPOSE. APPLE DOES NOT WARRANT THAT THE 
FUNCTIONS CONTAINED IN THE APPLE SOFTWARE WILL MEET YOUR 
REQUIREMENTS, OR THAT THE OPERATION OF THE APPLE SOFTWARE 
WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT DEFECTS IN THE 
APPLE SOFTWARE WILL BE CORRECTED. FURTHERMORE, APPLE 
DOES NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING 
THE USE OR THE RESULTS OF THE USE OF THE APPLE SOFTWARE OR 
RELATED DOCUMENTATION IN TERMS OF THEIR CORRECTNESS, 
ACCURACY, RELIABILITY, OR OTHERWISE. NO ORAL OR WRITTEN 
INFORMATION OR ADVICE GIVEN BY APPLE OR AN APPLE 
AUTHORIZED REPRESENTATIVE SHALL CREATE A WARRANTY OR IN 
ANY WAY INCREASE THE SCOPE OF THIS WARRANTY. SHOULD THE 
APPLE SOFTWARE PROVE DEFECTIVE, YOU (AND NOT APPLE OR AN 
APPLE AUTHORIZED REPRESENTATIVE) ASSUME THE ENTIRE COST OF 
ALL NECESSARY SERVICING, REPAIR OR CORRECTION. SOME STATES 
DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE 
ABOVE EXCLUSION MAY NOT APPLY TO YOU. 

9. limitation of Liability. UNDER NO CIRCUMSTANCES INCLUDING 
NEGLIGENCE, SHALL APPLE BE LIABLE FOR ANY INCIDENTAL, 

SPECIAL OR CONSEQUENTIAL DAMAGES THAT RESULT FROM THE USE 
OR INABILITY TO USE THE APPLE SOFTWARE OR RELATED 
DOCUMENTATION, EVEN IF APPLE OR AN APPLE AUTHORIZED 
REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH 
DAMAGES. SOME STATES DO NOT ALLOW THE LIMITATION OR 
EXCLUSION OF LIABILITY FOR INCIDENTAL OR CONSEQUENTIAL 
DAMAGES SO THE ABOVE LIMITATION OR EXCLUSION MAY NOT 
APPLY TO YOU. 

In no event shall Apple's total liability to you for all damages, losses, and 
causes of action (whether in contraa, tort (including negligence) or 
otherwise) exceed the amount paid by you for the Apple Software. 

10. Controlling Law and Severability. This License shall be governed 
by and construed in accordance with the laws of the United States and the 
State of California, as applied to agreements entered into and to be 
performed entirely within California between California residents. If for 
any reason a court of competent jurisdiction finds any provision of this 
License, or portion thereof, to be unenforceable, that provision of the 
License shall be enforced to the maximum extent permissible so as to effea 
the intent of the parties, and the remainder of this License shall continue in 
full force and effea. 

11. Complete Agreement. This License constitutes the entire 
agreement between the parties with respea to the use of the Apple 
Software and related documentation, and supersedes all prior or 
contemporaneous understandings or agreements, written or oral, 
regarding such subjea matter. No amendment to or modification of this 
License will be binding unless in writing and signed by a duly authorized 
representative of Apple. 
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